Bot Platform API

Introduction

A modern communication platform has been created in Gap messenger for developers. It helps developers to create their own business or bots for their contents or applications on Gap messenger’s API. In order to use these feature for your project, you just need to go to Developer centre of Gap messenger, and create your bot and connect.


What does this feature offer?
  • Send a message to any registered user on the robots (via chat or mobile id)
  • Send simple and multimedia messages (text, image, video, audio etc ...)
  • Receive messages from users.
  • Providing a user-selectable option (Reply keyboard)
  • Payment Options (Payment API)

A bot example

Users are going to know about the weather conditions of a city over the next few days. To do this, the process below is done. The city name must be sent to the bot by the user. After receiving the city’s name, Developer API will be finding the meteorological condition from related websites. Then the Results will be shown to your user as an image or text.

Types of bots

بطور کلی ربات‌ها به دو دسته تعاملی و اطلاع رسانی تقسیم می‌شوند که در جدول ذیل مشاهده می‌کنید:

Bot type Methods of sending content Description
collaborative - ربات تعاملی، بصورت دو طرفه است و قابلیت ارسال و دریافت پیام را دارد.
Notification group ربات اطلاع رسانی گروهی، عملکردی مشابه کانال دارد و فقط مدیر ربات امکان ارسال پیام به کاربران را دارد.
Notification individual ربات اطلاع رسانی گروهی، دقیقا مانند ربات اطلاع رسانی گروهی است با این تفاوت که مدیر ربات می‌تواند برای هر کاربر پیامی اختصاصی ارسال کند. در حقیقت یک کانال خصوصی بین مدیر و کاربر است.

Start of work

Bot platform

Gap messenger lets developers easily create and manage their bots by using management panel on the developer centre. To get started with the Bots, first of all, enter the developer panel via the following URL.

https://my.gap.im

صفحه ورود پرتال توسعه‌دهندگان

One-time password

To use this method, just enter your mobile number that you already registered for the Gap messenger. Enter the code that sent to your mobile to access the development panel.


Sign in with QR code

To enter the panel, just enter the Gap via your mobile phone. Go to the menu and choose login to the web with QR code. Scan the QRcode on the website and wait to log in to your management panel.


Create a new robot

To create a new robot after entering the developer panel, you can fill out the information you need with the help of the site menu and the bot options. Then create a robot on the opened page.

صفحه ایجاد ربات

  • اگر ربات را از نوع اطلاع رسانی ایجاد کنید، کاربر قادر به ارسال پیام برای برنامه شما نیست. (مشابه کانال ارتباط یک طرفه است)
  • اگر ربات را از نوع تعاملی ایجاد کنید، کاربران می‌توانند برای شما پیام ارسال کنند.
  • اگر نحوه ارسال محتوا فردی باشد، هنگام ارسال پیام، شما باید پیام را برای تک تک کاربران بصورت جداگانه ارسال کنید.
  • اگر نحوه ارسال محتوا گروهی باشد، برای ارسال پیام کافیست در قسمت chat_id شناسه ربات را ارسال کنید.

بصورت کلی اگر ربات شما عملکردی مشابه کانال دارد، بهتر است ربات را از نوع اطلاع رسانی و نحوه ارسال محتوا را گروهی انتخاب کنید، و اگر شما قصد ایجاد یک ربات دو طرفه(امکان ارسال و دریافت پیام) را دارید بهتر است نوع ربات تعاملی انتخاب شود.


Get Token

در صورت تکمیل صحیح اطلاعات مورد نیاز، هنگام ایجاد ربات، مرورگر شما را به لیست ربات‌هایی که ایجاد کرده‌اید، هدایت می‌کند که در این صفحه می‌توانید با کلیک روی آیکن ، جزئیات ربات و توکن مورد نیاز برای ارتباط با آن را مشاهده، کپی و یا تغییر دهید.

Work via API

Basic Description

به طور کلی روال کار با API به دو بخش ارسال اطلاعات کاربر (عضویت در ربات و پیام‌های ارسالی کاربر) به برنامه توسعه دهندگان و دیگری ارسال از برنامه توسعه دهندگان به کاربران گپ تقسیم می‌شود.

روال دریافت به این گونه است که هنگامی که کاربران اقدام به عضویت در ربات شما می‌کنند و یا متن، تصویر، فایل و ویدئویی را از داخل ربات برای شما ارسال می‌کنند، API اطلاعات دریافتی را با یک درخواست به صورت ‍‍POST به مسیری که در هنگام ایجاد ربات در سیستم ثبت شده است (لینک خارجی)، ارسال می‌کند.

و همچنین روال ارسال از برنامه توسعه دهندگان نیز به این شکل است که یک درخواست از برنامه توسعه دهنده به API گپ ارسال می‌شود که نکته مهم وجود token مربوط به ربات در هدر با نام token می‌باشد که برای اعتبارسنجی برنامه از آن استفاده می‌شود و توسعه دهنده پس از ساخت ربات در پرتال توسعه دهندگان می‌تواند به آن دسترسی پیدا کند.


Receive messages from robot users

همه پیام‌هایی که کاربران به ربات‌های تعاملی ارسال می‌نمایند، به صورت ‍‍POST به آدرسی که شما در هنگام ایجاد ربات در فیلد callback وارد کرده‌اید، ارسال می‌شوند.

Parameter Type Description
chat_id integer The unique user ID
from string An JSON type array that includes the id, name and username of the user registered in the robot.
type string Specifies the type of data that sent by the user
data string Data content that sent by user
Sending information to the user

انواع پیام‌هایی که از طرف گپ به آدرس callback ربات شما بصورت POST ارسال می‌شود، به شرح ذیل است:

Join user:
Parameter Type Description
chat_id integer The unique user ID
type string Specifies the type of data that sent by the user. In this type of message, the constant value is join.
Leave user:
Parameter Type Description
chat_id integer The unique user ID
type string Specifies the type of data that sent by the user. In this type of message, the constant value is leave.
Receive text message:
Parameter Type Description
chat_id integer The unique user ID
type string Specifies the type of data that sent by the user. In this type of message, the constant value is text.
from string An JSON type array that includes the id, name and username of the user registered in the robot.
data string Data content that sent by user
Receive image:
Parameter Type Description
chat_id integer The unique user ID
type string Specifies the type of data that sent by the user. In this type of message, the constant value is image.
from string An JSON type array that includes the id, name and username of the user registered in the robot.
data string An JSON type array that contains image file information.

Example: Data value when receiving image from the user:

{
	"screenshots":{
		"64":"https://storage.gap.im/assets/images/10/201810/1522/39c28fc5a5-5bc835edc2fbb817018b81f3.jpeg?configs=eyJzaXplIjoieDY0In0=",
		"128":"https://storage.gap.im/assets/images/10/201810/1522/8f22940818-5bc835edc2fbb817018b81f3.jpeg?configs=eyJzaXplIjoieDEyOCJ9",
		"256":"https://storage.gap.im/assets/images/10/201810/1522/b75f780440-5bc835edc2fbb817018b81f3.jpeg?configs=eyJzaXplIjoieDI1NiJ9",
		"512":"https://storage.gap.im/assets/images/10/201810/1522/4dc258430e-5bc835edc2fbb817018b81f3.jpeg?configs=eyJzaXplIjoieDUxMiJ9"
	},
	"type":"image",
	"path":"https://storage.gap.im/assets/images/10/201810/1522/866e10775e-5bc835edc2fbb817018b81f3.jpeg?configs=W10=",
	"tags":null,
	"width":512,
	"height":512,
	"duration":null,
	"filesize":34376,
	"filename":"image.jpeg",
	"desc":"کپشن تصویر"
}
Receive audio:
Parameter Type Description
chat_id integer The unique user ID
type string Specifies the type of data that sent by the user. In this type of message, the constant value is audio.
from string An JSON type array that includes the id, name and username of the user registered in the robot.
data string An JSON type array that contains audio file information.

Example: Data value when receiving audio from the user:

{
	"screenshots":null,
	"type":"audio",
	"path":"https://storage.gap.im/assets/media/10/201810/1522/67c7128a2e-5bcaedb0c2fbb85f008b8279.mp3?configs=W10=",
	"tags":{
		"album_artist":"Homayoun Shajarian",
		"album":"Irane Man",
		"artist":"Homayoun Shajarian",
		"genre":"Persian",
		"title":"Irane Man.mp3",
		"track":"01",
		"date":"2018",
		"filename":"11_Irane_Man.mp3"
	},
	"width":600,
	"height":600,
	"duration":405.34204,
	"filesize":16425508,
	"filename":"11_Irane_Man.mp3"
}
Receive video:
Parameter Type Description
chat_id integer The unique user ID
type string Specifies the type of data that sent by the user. In this type of message, the constant value is video.
from string An JSON type array that includes the id, name and username of the user registered in the robot.
data string An JSON type array that contains video file information.

Example: Data value when receiving video from the user:

{
	"screenshots":{
		"64":"https://storage.gap.im/assets/images/10/201810/1522/ea2903da88-5bcaf92fc2fbb827018b8246.mp4.jpg?configs=eyJzaG90IjoiMTAlIiwidmlkZW8iOiIyMDE4MTBcLzE1MjJcLzViY2FmOTJmYzJmYmI4MjcwMThiODI0Ni5tcDQiLCJzaXplIjoieDY0In0=",
		"128":"https://storage.gap.im/assets/images/10/201810/1522/d1b4581b46-5bcaf92fc2fbb827018b8246.mp4.jpg?configs=eyJzaG90IjoiMTAlIiwidmlkZW8iOiIyMDE4MTBcLzE1MjJcLzViY2FmOTJmYzJmYmI4MjcwMThiODI0Ni5tcDQiLCJzaXplIjoieDEyOCJ9",
		"256":"https://storage.gap.im/assets/images/10/201810/1522/1872622952-5bcaf92fc2fbb827018b8246.mp4.jpg?configs=eyJzaG90IjoiMTAlIiwidmlkZW8iOiIyMDE4MTBcLzE1MjJcLzViY2FmOTJmYzJmYmI4MjcwMThiODI0Ni5tcDQiLCJzaXplIjoieDI1NiJ9",
		"512":"https://storage.gap.im/assets/images/10/201810/1522/5ca0f4692a-5bcaf92fc2fbb827018b8246.mp4.jpg?configs=eyJzaG90IjoiMTAlIiwidmlkZW8iOiIyMDE4MTBcLzE1MjJcLzViY2FmOTJmYzJmYmI4MjcwMThiODI0Ni5tcDQiLCJzaXplIjoieDUxMiJ9"
	},
	"type":"video",
	"path":"https://storage.gap.im/assets/media/10/201810/1522/1710ad2414-5bcaf92fc2fbb827018b8246.mp4?configs=W10=",
	"tags":null,
	"width":848,
	"height":478,
	"duration":185,
	"filesize":32743613,
	"filename":"HD_2.1_1540028537.mp4",
	"desc":""

}
Receive voice:
Parameter Type Description
chat_id integer The unique user ID
type string Specifies the type of data that sent by the user. In this type of message, the constant value is voice.
from string An JSON type array that includes the id, name and username of the user registered in the robot.
data string An JSON type array that contains voice file information.

Example: Data value when receiving voice from the user:

{
	"screenshots":null,
	"type":"voice",
	"path":"https://storage.gap.im/assets/media/10/201810/1522/0d9def8260-5bcb2057c2fbb8b5008b81e6.ogg?configs=W10=",
	"tags":null,
	"width":null,
	"height":null,
	"duration":1.2,
	"filesize":3496,
	"filename":"1540038740564.ogg",
	"wavebytes":"AAAAAAAAAAAAAEKIEcYgQwhRyAhhjLRcYioZyo4p5phSTGLFmJSQOYYVlNB1b51VikkOIZVOOScZVMoxRREC"
}
Receive file:
Parameter Type Description
chat_id integer The unique user ID
type string Specifies the type of data that sent by the user. In this type of message, the constant value is file.
from string An JSON type array that includes the id, name and username of the user registered in the robot.
data string An JSON type array that contains file information.

Example: Data value when receiving file from the user:

{
	"screenshots":null,
	"type":"file",
	"path":"https://storage.gap.im/assets/file/10/201810/1522/dbba87b01f-5bcb223dc2fbb8e9008b82aa?configs=W10=",
	"tags":null,
	"width":null,
	"height":null,
	"duration":null,
	"filesize":2524109,
	"filename":"20181006_090943_01.jpeg"
}
Receive contact:
Parameter Type Description
chat_id integer The unique user ID
type string Specifies the type of data that sent by the user. In this type of message, the constant value is contact.
from string An JSON type array that includes the id, name and username of the user registered in the robot.
data string An JSON type array that contains contact information.

Example: Data value when receiving contact from the user:

{
	"name":"Ehsan Sabet",
	"phone":"+989356167766"
}
Receive location:
Parameter Type Description
chat_id integer The unique user ID
type string Specifies the type of data that sent by the user. In this type of message, the constant value is location.
from string An JSON type array that includes the id, name and username of the user registered in the robot.
data string An JSON type array that contains location information.

Example: Data value when receiving location from the user:

{
	"lat":"36.297611661967245",
	"long":"59.602204039692886",
	"desc":""
}
Receive form:
Parameter Type Description
chat_id integer The unique user ID
type string Specifies the type of data that sent by the user. In this type of message, the constant value is submitForm.
from string An JSON type array that includes the id, name and username of the user registered in the robot.
data string An JSON type array that contains form information.

Example: Data value when receiving submitForm from the user:

{
	"data":"name=Ehsan&married=y&city=mashhad&address=Iran&agree=true",
	"message_id":97,
	"callback_id":"N7YcI5rAlX2sEFmh"
}
دریافت اطلاعات هنگام کلیک روی دکمه‌ inline دارای cb_data توسط کاربر:
Parameter Type Description
chat_id integer The unique user ID
type string Specifies the type of data that sent by the user. In this type of message, the constant value is triggerButton.
from string An JSON type array that includes the id, name and username of the user registered in the robot.
data string An JSON type array that contains trigger button information.

Example: Data value when receiving triggerButton from the user:

{
	"data":"yes",
	"message_id":98,
	"callback_id":"XoXN/QCEMd4JeICk"
}
Payment information:
Parameter Type Description
chat_id integer The unique user ID
type string Specifies the type of data that sent by the user. In this type of message, the constant value is paycallback.
from string An JSON type array that includes the id, name and username of the user registered in the robot.
data string An JSON type array that contains payment information.

هنگامی که کاربر با استفاده از دکمه‌های inline پرداخت درون برنامه‌ای انجام می‌دهد، این مقادیر به لینک callback شما ارسال می‌شود.

Example: Data value when receiving paycallback from the user:

{
	"ref_id":"123456",
	"message_id":"99",
	"status":"success"
}
Invoice information:
Parameter Type Description
chat_id integer The unique user ID
type string Specifies the type of data that sent by the user. In this type of message, the constant value is invoicecallback.
from string An JSON type array that includes the id, name and username of the user registered in the robot.
data string An JSON type array that contains invoice information.

هنگامی که کاربر با استفاده از دکمه‌های inline یک صورتحساب پرداخت می‌کند، این مقادیر به لینک callback شما ارسال می‌شود.

Example: Data value when receiving invoicecallback from the user:

{
	"invoiceId":"5bcd7f7ca74ad8015d65205d"
}

توکن ربات (Token)

هر درخواستی که شما بعنوان توسعه دهنده به گپ ارسال می‌کنید، جهت احراز هویت نیاز به توکن دارد، بعد از ایجاد ربات از طریق بات پلتفرم، توکن برای شما ایجاد می‌شود.

هنگام ارسال هر درخواستی به سرور باید توکن ربات را در Header و با نام token ارسال نمایید.

ارسال پیام به کاربران

برای ارسال پیام به کاربران ربات،‌ باید پارامترهای لازم را به صورت POST به آدرس https://api.gap.im/sendMessage ارسال نمایید.

chat_id

نکته مهم: برای ارسال پیام به کاربران با توجه به نوع ربات مقدار chat_id تغییر میکند. که در جدول زیر می‌توانید انواع این مقادیر را مشاهده کنید:

مقدار chat_id در انواع ربات‌ها:
Parameter نوع پارامتر Type نحوه ارسال Description
chat_id integer ربات تعاملی - شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
string شماره موبایل کاربر عضو شده در ربات با فرمت +989123456789
integer ربات اطلاع رسانی فردی شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
string شماره موبایل کاربر عضو شده در ربات با فرمت +989123456789
string گروهی شناسه ربات به همراه @ بطور مثال: @bot
انواع ارسال پیام ربات به کاربر
ارسال پیام متنی (Text) به کاربر:
Parameter Type Description
chat_id integer / string chat_id detail
type string Specifies the type of sent data. That's the kind of constant text in this type of message.
data string Your text or content
reply_keyboard string Adding a reply keyboard to the message. This value should be sent to JSON. (reply_keyboard detail )
inline_keyboard string Adding a inline keyboard to the message. This value should be sent to JSON. (inline_keyboard detail )
form string Adding a form to the message. This value should be sent to JSON. (form detail)
Response
Status code Response Description
200 {"id": 1333} Your sent message ID is in fact your message_id
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: type"} The type parameter is not valid.
400 {"error":"Invalid data passed: data"} The data parameter is not valid.
400 {"error":"Invalid data passed: reply_keyboard"} The reply_keyboard parameter is not valid.
400 {"error":"Invalid data passed: inline_keyboard"} The inline_keyboard parameter is not valid.
400 {"error":"Invalid data passed: form"} The form parameter is not valid.
ارسال تصویر (Image) به کاربر:
Parameter Type Description
chat_id integer / string chat_id detail
type string Specifies the type of sent data. That's the kind of constant image in this type of message.
data string Output file upload method, as JSON (Upload)
reply_keyboard string Adding a reply keyboard to the message. This value should be sent to JSON. (reply_keyboard detail )
inline_keyboard string Adding a inline keyboard to the message. This value should be sent to JSON. (inline_keyboard detail )
form string Adding a form to the message. This value should be sent to JSON. (form detail)

برای ارسال تصویر به کاربران ربات،‌ باید پارامترهای جدول فوق را به صورت POST به آدرس https://api.gap.im/sendMessage به همراه توکن ارسال نمایید.

Response
Status code Response Description
200 {"id": 1333} Your sent message ID is in fact your message_id
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: type"} The type parameter is not valid.
400 {"error":"Invalid data passed: data"} The data parameter is not valid.
400 {"error":"Invalid data passed: reply_keyboard"} The reply_keyboard parameter is not valid.
400 {"error":"Invalid data passed: inline_keyboard"} The inline_keyboard parameter is not valid.
400 {"error":"Invalid data passed: form"} The form parameter is not valid.
ارسال فایل صوتی (Audio) به کاربر:
Parameter Type Description
chat_id integer / string chat_id detail
type string Specifies the type of sent data. That's the kind of constant audio in this type of message.
data string Output file upload method, as JSON (Upload)
reply_keyboard string Adding a reply keyboard to the message. This value should be sent to JSON. (reply_keyboard detail )
inline_keyboard string Adding a inline keyboard to the message. This value should be sent to JSON. (inline_keyboard detail )
form string Adding a form to the message. This value should be sent to JSON. (form detail)

برای ارسال فایل صوتی به کاربران ربات،‌ باید پارامترهای جدول فوق را به صورت POST به آدرس https://api.gap.im/sendMessage به همراه توکن ارسال نمایید.

Response
Status code Response Description
200 {"id": 1333} Your sent message ID is in fact your message_id
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: type"} The type parameter is not valid.
400 {"error":"Invalid data passed: data"} The data parameter is not valid.
400 {"error":"Invalid data passed: reply_keyboard"} The reply_keyboard parameter is not valid.
400 {"error":"Invalid data passed: inline_keyboard"} The inline_keyboard parameter is not valid.
400 {"error":"Invalid data passed: form"} The form parameter is not valid.
ارسال ویدیو (Video) به کاربر:
Parameter Type Description
chat_id integer / string chat_id detail
type string Specifies the type of sent data. That's the kind of constant video in this type of message.
data string Output file upload method, as JSON (Upload)
reply_keyboard string Adding a reply keyboard to the message. This value should be sent to JSON. (reply_keyboard detail )
inline_keyboard string Adding a inline keyboard to the message. This value should be sent to JSON. (inline_keyboard detail )
form string Adding a form to the message. This value should be sent to JSON. (form detail)

برای ارسال ویدیو به کاربران ربات،‌ باید پارامترهای جدول فوق را به صورت POST به آدرس https://api.gap.im/sendMessage به همراه توکن ارسال نمایید.

Response
Status code Response Description
200 {"id": 1333} Your sent message ID is in fact your message_id
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: type"} The type parameter is not valid.
400 {"error":"Invalid data passed: data"} The data parameter is not valid.
400 {"error":"Invalid data passed: reply_keyboard"} The reply_keyboard parameter is not valid.
400 {"error":"Invalid data passed: inline_keyboard"} The inline_keyboard parameter is not valid.
400 {"error":"Invalid data passed: form"} The form parameter is not valid.
ارسال صدا (Voice) به کاربر:
Parameter Type Description
chat_id integer / string chat_id detail
type string Specifies the type of sent data. That's the kind of constant voice in this type of message.
data string Output file upload method, as JSON (Upload)
reply_keyboard string Adding a reply keyboard to the message. This value should be sent to JSON. (reply_keyboard detail )
inline_keyboard string Adding a inline keyboard to the message. This value should be sent to JSON. (inline_keyboard detail )
form string Adding a form to the message. This value should be sent to JSON. (form detail)

برای ارسال صدا به کاربران ربات،‌ باید پارامترهای جدول فوق را به صورت POST به آدرس https://api.gap.im/sendMessage به همراه توکن ارسال نمایید.

Response
Status code Response Description
200 {"id": 1333} Your sent message ID is in fact your message_id
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: type"} The type parameter is not valid.
400 {"error":"Invalid data passed: data"} The data parameter is not valid.
400 {"error":"Invalid data passed: reply_keyboard"} The reply_keyboard parameter is not valid.
400 {"error":"Invalid data passed: inline_keyboard"} The inline_keyboard parameter is not valid.
400 {"error":"Invalid data passed: form"} The form parameter is not valid.
ارسال فایل (File) به کاربر:
Parameter Type Description
chat_id integer / string chat_id detail
type string Specifies the type of sent data. That's the kind of constant file in this type of message.
data string Output file upload method, as JSON (Upload)
reply_keyboard string Adding a reply keyboard to the message. This value should be sent to JSON. (reply_keyboard detail )
inline_keyboard string Adding a inline keyboard to the message. This value should be sent to JSON. (inline_keyboard detail )
form string Adding a form to the message. This value should be sent to JSON. (form detail)

برای ارسال فایل به کاربران ربات،‌ باید پارامترهای جدول فوق را به صورت POST به آدرس https://api.gap.im/sendMessage به همراه توکن ارسال نمایید.

Response
Status code Response Description
200 {"id": 1333} Your sent message ID is in fact your message_id
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: type"} The type parameter is not valid.
400 {"error":"Invalid data passed: data"} The data parameter is not valid.
400 {"error":"Invalid data passed: reply_keyboard"} The reply_keyboard parameter is not valid.
400 {"error":"Invalid data passed: inline_keyboard"} The inline_keyboard parameter is not valid.
400 {"error":"Invalid data passed: form"} The form parameter is not valid.
ارسال شماره تلفن (Contact) به کاربر:
Parameter Type Description
chat_id integer / string chat_id detail
type string Specifies the type of sent data. That's the kind of constant contact in this type of message.
data string یک JSON که شامل کلیدهای phone و name است.
reply_keyboard string Adding a reply keyboard to the message. This value should be sent to JSON. (reply_keyboard detail )
inline_keyboard string Adding a inline keyboard to the message. This value should be sent to JSON. (inline_keyboard detail )
form string Adding a form to the message. This value should be sent to JSON. (form detail)

مثال: مقدار data در هنگام ارسال شماره تلفن به کاربر

{
	"phone":"+989123456789",
	"name":"Name Family"
}

برای ارسال شماره تلفن به کاربران ربات،‌ باید پارامترهای جدول فوق را به صورت POST به آدرس https://api.gap.im/sendMessage به همراه توکن ارسال نمایید.

Response
Status code Response Description
200 {"id": 1333} Your sent message ID is in fact your message_id
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: type"} The type parameter is not valid.
400 {"error":"Invalid data passed: data"} The data parameter is not valid.
400 {"error":"Invalid data passed: reply_keyboard"} The reply_keyboard parameter is not valid.
400 {"error":"Invalid data passed: inline_keyboard"} The inline_keyboard parameter is not valid.
400 {"error":"Invalid data passed: form"} The form parameter is not valid.
ارسال موقعیت جغرافیایی (Location) به کاربر:
Parameter Type Description
chat_id integer / string chat_id detail
type string Specifies the type of sent data. That's the kind of constant location in this type of message.
data string یک JSON که شامل کلیدهای lat، long و desc است.
reply_keyboard string Adding a reply keyboard to the message. This value should be sent to JSON. (reply_keyboard detail )
inline_keyboard string Adding a inline keyboard to the message. This value should be sent to JSON. (inline_keyboard detail )
form string Adding a form to the message. This value should be sent to JSON. (form detail)

مثال: مقدار data در هنگام ارسال شماره تلفن به کاربر

{
	"lat":"36.2605",
	"long":"59.6168",
	"desc":"Mashhad"
}

برای ارسال موقعیت جغرافیایی به کاربران ربات،‌ باید پارامترهای جدول فوق را به صورت POST به آدرس https://api.gap.im/sendMessage به همراه توکن ارسال نمایید.

Response
Status code Response Description
200 {"id": 1333} Your sent message ID is in fact your message_id
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: type"} The type parameter is not valid.
400 {"error":"Invalid data passed: data"} The data parameter is not valid.
400 {"error":"Invalid data passed: reply_keyboard"} The reply_keyboard parameter is not valid.
400 {"error":"Invalid data passed: inline_keyboard"} The inline_keyboard parameter is not valid.
400 {"error":"Invalid data passed: form"} The form parameter is not valid.
ارسال Action

با استفاده از این قابلیت می‌توانید یک Action برای کاربر ارسال کنید.

برای ارسال Action باید پارامترهای ذیل را بصورت POST به https://api.gap.im/sendAction به همراه توکن ارسال نمایید.

ارسال Action به کاربر:
Parameter Type Description
chat_id integer / string chat_id detail
type string نوع action ارسالی را مشخص می‌کند، که در حال حاضر فقط یک نوع action پشتیبانی می‌شود. و مقدار آن باید برابر با typing باشد.
Response
Status code Response Description
200 Action با موفقیت برای کاربر ارسال شده است.
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: type"} The type parameter is not valid.
آپلود فایل

برای ارسال تصویر، ویدیو، فایل صوتی، صدا و ... باید ابتدا آن را با استفاده از این متود، در سرورهای گپ آپلود کرده،و پس از این که آپلود با موفقیت انجام شد رشته‌ای encode شده در پاسخ درخواست دریافت خواهید کرد که باید این رشته را به همراه درخواست اصلی خود با استفاده از سایر متودها مجدد به api ارسال کنید. همچنین شما می‌توانید با ذخیره این رشته، در ارسال‌های بعدی بارها از آن بدون آپلود مجدد استفاده کنید.

برای آپلود فایل باید پارامترهای ذیل را بصورت POST به https://api.gap.im/upload به همراه توکن ارسال نمایید.

آپلود فایل:
Parameter Type Required Description فرمت پیشنهادی
chat_id integer / string Yes توضیحات مربوط به chat_id
image File No فایل تصویر مورد نظر شما برای آپلود بصورت multipart/form-data jpg, png, jpeg
video File No فایل ویدیو مورد نظر شما برای آپلود بصورت multipart/form-data mp4 (h264 baseline)
voice File No فایل صدا مورد نظر شما برای آپلود بصورت multipart/form-data ogg
audio File No فایل صوتی مورد نظر شما برای آپلود بصورت multipart/form-data mp3
file File No فایل مورد نظر شما برای آپلود بصورت multipart/form-data *
desc string No توضیحات مربوط به فایل ارسالی شما
Response
Status code Response Description
200 JSON حاوی اطلاعات فایل آپلود شده بر روی سرور. فایل با موفقیت آپلود شده است.
403 - توکن ارسالی معتبر نمی‌باشد.
500 - حجم فایل ارسالی و یا نوع آن معتبر نمی‌باشد.
حجم مجاز آپلود فایل در انواع ربات‌ها:
Type نحوه ارسال حداکثر حجم مجاز آپلود
ربات تعاملی - 50 مگابایت
ربات اطلاع رسانی فردی 50 مگابایت
ربات اطلاع رسانی گروهی 500 مگابایت
ویرایش پیام‌های ارسالی به کاربران

شما می‌توانید پیام‌‌هایی که ارسال کرده‌اید را با استفاده از این متود ویرایش کنید.

برای ویرایش باید پارامترهای ذیل را بصورت POST به https://api.gap.im/editMessage به همراه توکن ارسال نمایید.

ویرایش پیام ارسال شده به کاربر:
Parameter Type Required Description
chat_id integer / string Yes chat_id detail
message_id integer Yes message_id پیامی که قصد ویرایش آن را دارید.
data string Yes متن جدیدی که قصد ارسال آن را دارید.
inline_keyboard string No Adding a inline keyboard to the message. This value should be sent to JSON. (inline_keyboard detail )
Response
Status code Response Description
200 - پیام با موفقیت ویرایش شد.
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: message_id"} The message_id parameter is not valid.
400 {"error":"Invalid data passed: inline_keyboard"} The inline_keyboard parameter is not valid.
حذف پیام‌های ارسال شده به کاربران

شما می‌توانید پیام‌‌هایی که ارسال کرده‌اید را با استفاده از این متود حذف کنید.

برای حذف باید پارامترهای ذیل را بصورت POST به https://api.gap.im/deleteMessage به همراه توکن ارسال نمایید.

حذف پیام ارسال شده به کاربر:
Parameter Type Required Description
chat_id integer / string Yes chat_id detail
message_id integer Yes message_id پیامی که قصد حذف آن را دارید.
Response
Status code Response Description
200 - پیام با موفقیت حذف شد.
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: message_id"} The message_id parameter is not valid.
Answer Callback

اگر کاربری روی دکمه‌ای از نوع Inline keyboard که دارای مقدار cb_data است کلیک کند، شما می‌توانید یک alert و یا tooltip با متن دلخواه به کاربر نمایش دهید.

برای ارسال Answer Callback باید پارامترهای ذیل را بصورت POST به https://api.gap.im/answerCallback به همراه توکن ارسال نمایید.

ارسال Answer Callback به کاربر:
Parameter Type Required Description
chat_id integer Yes شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
callback_id integer Yes آی‌دی دکمه کلیک شده توسط کاربر، که هنگام کلیک بصورت triggerButton برای برنامه توسعه دهنده ارسال می‌شود.
text string Yes متن پیامی که قصد نمایش آن به کاربر را دارید.
show_alert boolean Yes نوع نمایش پیغام به کاربر را مشخص می‌کند که در صورت true بودن پیام به صورت alert و در صورت وجود مقدار false به شکل tooltip نمایش داده خواهد شد .
Response
Status code Response Description
200 - پیغام با موفقیت ارسال شد.
403 - The token or chat_id parameter is not valid.
ارسال صورتحساب برای کاربر

در پیام‌رسان گپ شما می‌توانید برای اعضاء ربات خود با استفاده از این متود صورتحساب ارسال کنید. پس از صدور، کاربر با کلیک بر روی دکمه پرداخت صورتحساب وارد صفحه کیف پول گپ شده و می‌تواند با استفاده از روش‌های موجود نسبت به پرداخت صورتحساب صادر شده اقدام نماید.

برای ارسال صورتحساب باید پارامترهای ذیل را بصورت POST به https://api.gap.im/invoice به همراه توکن ارسال نمایید.

ارسال صورتحساب:
Parameter Type Required Description
chat_id integer Yes شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
amount integer Yes مبلغ صورتحساب که کاربر باید پرداخت کند.
currency string No این مقدار مشخص کننده واحد پولی صورتحساب است که می‌توانید یکی از مقادیر IRR (ریال) و یا USD (دلار) را وارد کنید. اگر این مقدار وارد نشود بطور پیشفرض صورتحساب ریالی صادر خواهد شد.
description string Yes توضیحات مربوط به صورتحساب پرداختی که به کاربر نمایش داده می‌شود.

نکته: پیشنهاد می‌شود شما مقدار invoice_id را جهت استفاده در درخواست های بعدی ذخیره کنید.

Response
Status code Response Description
200 {"id":"5bd04ea7a74ad805f8045b91"} مقدار id، همان invoice_id صورتحساب ارسال شده برای کاربر می‌باشد.
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: amount"} محتوای پارامتر amount معتبر نمی‌باشد.
تایید صورتحساب

پس از پرداخت موفق صورتحساب توسط کاربر، لازم است توسعه دهنده نسبت به تایید این صورتحساب اقدام نماید، برای تایید صورتحساب باید پارامترهای ذیل را بصورت POST به https://api.gap.im/invoice/verify به همراه توکن ارسال نمایید.

تایید صورتحساب:
Parameter Type Required Description
chat_id integer Yes شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
ref_id string Yes invoice_id که در هنگام ارسال صورتحساب دریافت کرده‌اید.
Response
Status code Response Description
200 {"amount":10000,"status":"verified"} مقدار status، مشخص می‌کند که این صورتحساب پرداخت و تایید شده است و مقدار آن را نمایش می‌دهد.
403 - The token or chat_id parameter is not valid.
405 - مقدار ref_id معتبر نمی‌باشد.
استعلام صورتحساب

برای استعلام وضعیت صورتحسابی که قبلا برای کاربر ارسال کرده‌اید، باید پارامترهای ذیل را بصورت POST به https://api.gap.im/invoice/inquiry به همراه توکن ارسال نمایید.

استعلام صورتحساب:
Parameter Type Required Description
chat_id integer Yes شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
ref_id string Yes invoice_id که در هنگام ارسال صورتحساب دریافت کرده‌اید.
Response
Status code Response Description
200 {"status":"error"} مقدار status، مشخص می‌کند که این صورتحساب پرداخت نشده است و یا ref_id اشتباه است.
200 {"amount":10000,"status":"verified"} مقدار status، مشخص می‌کند که این صورتحساب پرداخت شده است و مقدار آن را نمایش می‌دهد.
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: ref_id"} The ref_id parameter is not valid.
پرداخت درون برنامه‌ای

پرداخت درون برنامه‌ای نوع دیگری از پرداخت وجه توسط کاربران در گپ می‌باشد و روش استفاده از آن بدین صورت است که می‌توان در هنگام ساخت inline keyboard یک دکمه به شکل زیر تغریف کرد. دکمه پرداخت درون برنامه‌ای یک JSON، شامل موارد ذیل است که باید در قسمت inline keyboard درج شود.

key های قابل استفاده در inline keyboard
Key Type Required Description
text string Yes این مقدار در حقیقت برچسب دکمه پرداخت دورن برنامه‌ای است.
amount integer Yes این مقدار به منظور گرفتن وجه از کاربر به شکل پرداخت درون برنامه‌ای می‌باشد.
currency string Yes این مقدار مشخص کننده واحد پول است. که در حال حاضر می‌تواند برای پرداخت‌های ریالی مقدار IRR و پرداخت گپسی مقدار coin را دریافت کند.
ref_id string Yes یک رشته Base64 شامل حروف و ارقام می‌باشد که در واقع یک کد منحصر بفرد است که توسط توسعه دهنده ایجاد شده و برای شناسایی کاربر پس از انجام روال پرداخت استفاده می‌شود. پس از انجام پرداخت توسط کاربر و یا به وجود آمدن خطا در روال پرداخت، گپ یک درخواست به منظور اعلام نتیجه برای توسعه دهنده ارسال می‌کند که از نوع payCallback و شامل مقدار ref_id نیز می‌باشد.
desc string Yes توضیحات مربوط به پرداخت که برای نمایش در لیست تراکنش‌ها استفاده می‌شود.

برای ایجاد دکمه پرداخت درون برنامه‌ای باید پارامترهای ذیل را بصورت POST به https://api.gap.im/sendMessage به همراه توکن ارسال نمایید.

ایجاد دکمه پرداخت درون برنامه‌ای:
Parameter Type Required Description
chat_id integer / string Yes chat_id detail
type string Yes Specifies the type of sent data. That's the kind of constant text in this type of message.
data string Yes Your text or content
inline_keyboard string Yes افزودن کیبورد از نوع inline حاوی دکمه پرداخت درون برنامه‌ای به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به inline_keyboard)

نکته: در هر نوع ارسال پیامی که شما امکان درج inline keyboard را داشته باشید، می‌توانید از پرداخت درون برنامه‌ای استفاده کنید، که در این مثال ما از ارسال پیام متنی استفاده کرده‌ایم.

مثال: محتوای پارامتر inline keyboard هنگام ایجاد دکمه پرداخت درون برنامه‌ای:

[
	[
		{
		"text":"پرداخت سکه",
		"amount":2,
		"currency":"coin",
		"ref_id":"XXXXXXX",
		"desc":"توضیحات مربوط به پرداخت برای نمایش در لیست تراکنش ها"
		}
	]
]
Response
Status code Response Description
200 {"id": 1333} Your sent message ID is in fact your message_id
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: type"} The type parameter is not valid.
400 {"error":"Invalid data passed: data"} The data parameter is not valid.
400 {"error":"Invalid data passed: inline_keyboard"} The inline_keyboard parameter is not valid.
تایید پرداخت درون برنامه‌ای

پس از انجام موفق پرداخت درون برنامه‌ای توسط کاربر، لازم است توسعه دهنده نسبت به تایید این پرداخت اقدام نماید، برای تایید باید پارامترهای ذیل را بصورت POST به https://api.gap.im/payment/verify به همراه توکن ارسال نمایید.

تایید پرداخت درون برنامه‌ای:
Parameter Type Required Description
chat_id integer Yes شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
ref_id string Yes ref_id که در هنگام ایجاد دکمه پرداخت درون برنامه‌ای توسط توسعه دهنده تولید شده است.
Response
Status code Response Description
200 {"amount":2,"status":"verified"} مقدار status، مشخص می‌کند که این پرداخت درون برنامه‌ای انجام و تایید شده است و مقدار آن را نمایش می‌دهد.
403 - The token or chat_id parameter is not valid.
405 - مقدار ref_id معتبر نمی‌باشد.
استعلام پرداخت درون برنامه‌ای

برای استعلام وضعیت پرداخت درون برنامه‌ای، که قبلا برای کاربر ارسال کرده‌اید، باید پارامترهای ذیل را بصورت POST به https://api.gap.im/payment/inquiry به همراه توکن ارسال نمایید.

استعلام پرداخت درون برنامه‌ای:
Parameter Type Required Description
chat_id integer Yes شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
ref_id string Yes ref_id که در هنگام ایجاد دکمه پرداخت توسط توسعه دهنده تولید شده است.
Response
Status code Response Description
200 {"status":"error"} مقدار status، مشخص می‌کند که این پرداخت درون برنامه‌ای انجام نشده است و یا ref_id اشتباه است.
200 {"amount":2,"status":"verified"} مقدار status، مشخص می‌کند که این پرداخت انجام شده است و مقدار آن را نمایش می‌دهد.
403 - The token or chat_id parameter is not valid.
400 {"error":"Invalid data passed: ref_id"} The ref_id parameter is not valid.

انواع Keyboard

برای دریافت اطلاعات کاربر به شکل ثابت و از پیش تعریف شده می توان از قابلیت ایجاد keyboard استفاده کرد. با استفاده از این قابلیت می توان به تعداد مورد نیاز دکمه برای کاربر تعریف کرد که پس از کلیک و یا tap بروی هر کدام از این دکمه ها توسط کاربر عملکردی که برای آن تعریف کرده اید انجام خواهد شد که این عمل می تواند شامل ارسال یک مقدار از سمت کاربر به سرور و یا باز کردن یک url در مرورگر کاربر باشد.

به طور کل دو نوع کیبورد در پیام رسان گپ قابل استفاده می‌باشد: Reply Keyboard و Inline Button

Reply Keyboard

از این نوع کیبورد برای دریافت مقادیر ثابت و از پیش تعریف شده و یا دریافت لوکیشن و شماره تلفن کاربر می‌توان استفاده کرد. این کیبورد شامل JSON مشابه کد ذیل است:

{
	"keyboard":[
		[
			{"yes":"بلی"},
			{"no":"خیر"}
		],[
			{"cancel":"انصراف"}
		]
	]
}

توجه داشته باشید که بعد از کلیک کاربر روی این دکمه‌ها پیامی مبنی بر اشتراک گذاری شماره تلفن و یا لوکیشن برای کاربر نمایش داده می‌شود و پس از تایید این پیام، مقادیر به برنامه شما ارسال می‌شود.

دریافت شماره تلفن و لوکیشن از کاربر

برای دریافت شماره تلفن و یا لوکیشن کاربر باید آرایه‌ای به شکل ذیل ایجاد کنید.

{
	"keyboard":[
		[
			{"$contact":"تلفن"},
			{"$location":"لوکیشن"}
		]
	]
}
Inline Keyboard

inline keyboard یا دکمه شیشه‌ای نوع دیگری از دکمه‌ها هستند که در پیام رسان گپ قابل استفاده هستند، از این دکمه‌ها می‌توان برای ارسال مقادیر مختلف، ارسال لینک و یاپرداخت درون برنامه‌ای استفاده کرد.

key های قابل استفاده در inline keyboard
Key Type Required Description
text string Yes متن دکمه که برای کاربر نمایش داده می‌شود.
cb_data string No هنگام کلیک بروی این دکمه، سرور یک درخواست از نوع triggerButton به سمت برنامه توسعه دهنده ارسال خواهد کرد که شامل مقدار cb_data می‌باشد.
url string No هنگام کلیک بروی این دکمه، مسیری که در مقابل این پارامتر قرار دارد در مرورگر کاربر باز خواهد شد.
open_in string No اگر دکمه‌ای که ساخته شده دارای مقدار url باشد، شما میتوانید نحوه بازشدن این لینک را مشخص کنید.
مقدار این key می‌تواند یک از این موارد باشد: browser, inline_browser, webview_full, webview_with_header, webview
amount integer No این مقدار به منظور گرفتن وجه از کاربر به شکل پرداخت درون برنامه‌ای می‌باشد.
currency string No این مقدار مشخص کننده واحد پول است. که در حال حاضر می‌تواند برای پرداخت‌های ریالی مقدار IRR و پرداخت گپسی مقدار coin را دریافت کند.
در صورت ارسال amount، ارسال این مقدار نیز الزامی است.
ref_id string No یک رشته Base64 شامل حروف و ارقام می‌باشد.
در صورت ارسال amount، ارسال این مقدار نیز الزامی است.
desc string No توضیحات مربوط به پرداخت که برای نمایش در لیست تراکنش‌ها استفاده می‌شود.
در صورت ارسال amount، ارسال این مقدار نیز الزامی است.

نحوه تعریف این نوع keyboard بدین شکل است:

[
	[
		{
			"text":"بلی",
			"cb_data":"yes"
		},{
			"text":"خیر",
			"cb_data":"no"
		}
	],[
		{
			"text":"وب سایت",
			"url":"http://google.com",
			"open_in":"webview_with_header"
		},{
			"text":"دونیت",
			"amount":2000,
			"currency":"IRR",
			"ref_id":"XXXXXXX",
			"desc":"توضیحات مربوط به پرداخت برای نمایش در لیست تراکنش ها"
		}
	]
]
ارسال فرم به کاربر:

پیام‌رسان گپ به توسعه دهندگان این امکان را می‌دهد که برای دریافت اطلاعات کاربران، از فرم استفاده کنند به این صورت که توسعه دهنده یک فرم به همراه فیلدهای مورد نیاز خود را برای کاربر ارسال می‌کند و در ادامه کاربر اطلاعات را در فرم وارد می‌کند و مجدد پیام رسان مقادیر وارد شده توسط کاربر را برای توسعه دهنده ارسال می‌نماید.

key های قابل استفاده در form
نام Description
name نام منحصر به فرد برای هر فیلد.
type نوع فیلد فرم که می‌تواند با یکی از مقادیر [text ,radio ,select ,textarea ,checkbox ,inbuilt ,submit] پر شود.
label نام نمایشی جلوی هر فیلد در فرم.
options زمانی که مقدار پارامتر type برابر با یکی از مقادیر [select ,radio] باشد می‌توانید گزینه‌های قابل انتخاب توسط کاربر را در این پارامتر مشخص کنید.
انواع فیلدهای قابل استفاده در form
Type Description
text برای دریافت متن کوتاه استفاده می‌شود.
radio دکمه رادیویی برای انتخاب یک مقدار از بین چندین مقدار استفاده می‌شود.
select لیست کشویی برای انتخاب یک مقدار از بین چندین مقدار استفاده می‌شود.
textarea برای دریافت متن طولانی و چند خطی از کاربر استفاده می‌شود.
checkbox چک باکس برای انتخاب یک مقدار یا چند مقدار از بین چندین مقدار استفاده می‌شود.
inbuilt برای اسکن بارکد و کیوآرکد استفاده می‌شود. که در این حالت مقدار value یکی از مقادیر [barcode, qrcode] است.
submit برای ارسال فرم استفاده می‌شود.

ساختار کلی فرم:

[
	{
		"name":"name", "type":"text", "label":"Name"
	},{
		"name":"married", "type":"radio", "label":"Married",
		"options":[
			{"y":"Yes"},
			{"n":"No"}
		]
	},{
		"name":"city", "type":"select", "label":"City",
		"options":[
			{"mah":"Mashhad"},
			{"teh":"Tehran"}
		]
	},{
		"name":"address", "type":"textarea", "label":"Address"
	},{
		"name":"test_bc", "type":"inbuilt", "value":"barcode", "label":"Scan barcode"
	},{
		"name":"test_qr", "type":"inbuilt", "value":"qrcode", "label":"Scan qr-code"
	},{
		"name":"agree", "type":"checkbox", "label":"I agree"
	},{
		"type":"submit", "label":"Save"
	}
]

API گیم سنتر گپ

در پیام‌رسان گپ، شما می‌توانید براحتی اطلاعات مربوط به بازی از جمله رکوردها و ... را با استفاده از API ارایه شده ذخیره و یا بازیابی کنید. همچنین با استفاده از اطلاعاتی که ارسال کرده اید، جدول بازی‌ را در بازه های زمانی مختلف دریافت و به کاربران نمایش دهید.

ذخیره اطلاعات بازیکن

برای ذخیره اطلاعات بازی مانند: امتیاز، باید پارامترهای ذیل را بصورت POST به https://api.gap.im/gameData به همراه توکن ارسال نمایید.

مقادیر ارسالی:
Parameter Type Required Description
chat_id integer Yes شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
type string Yes نوع data ارسالی را مشخص می‌کند، به منظور ذخیره ی امتیاز بازیکن این پارامتر را برابر high_score قرار دهید و در غیر این صورت هر نوع دیگری مختص به بازی خود را می توانید ارسال کنید. ذکر این نکته الزامی است که شما حداکثر قادر به ارسال ۲۵ type متفاوت هستید.
data string Yes مقداری که قصد ذخیره کردن آن را دارید در این قسمت قرار می‌گیرد. توجه داشته باشید که اگر type مورد نظر high_score است این مقدار حتما باید integer باشد و در غیر این صورت می تواند هر نوع داده ای را شامل شود . حداکثر سایز قابل قبول برای این پارامتر ۱۰ کیلوبایت است.
force Boolean No این پارامتر برای نوع داده ای high_score مورد استفاده قرار می گیرد و به صورت پیش فرض false است و چنانچه امتیاز فعلی از امتیاز قبلی کمتر باشد سرور آن را ذخیره نمی کند. اگر بنا به هرعلتی اعم از رخداد اشتباه یا تقلب تمایل به ذخیره ی امتیاز کمتر دارید این پارمتر را با مقدار true ارسال کنید.
Response
Status code Response Description
200 مقادیر ارسالی با موفقیت ذخیره شده است.
400 {"error": "Invalid data passed: type"} پارامتر type ارسال نشده است.
400 {"error": "type of score must be integer"} مقدار ارسالی برای score نامعتبر است.
400 {"error": "Max size of data can not be more than 10KB"} سایز داده ی ارسالی بیشتر از مقدار قابل قبول است.
400 {"error": "Number of data type can not be more than 25"} تعداد type ها از حداکثر قابل قبول بیشتر است.
دریافت اطلاعات بازیکن

برای دریافت اطلاعات بازی که قبلا با استفاده از تابع gameData ذخیره کرده‌اید، باید پارامترهای ذیل را بصورت POST به https://api.gap.im/getGameData به همراه توکن ارسال نمایید.

مقادیر ارسالی:
Parameter Type Required Description
chat_id integer Yes شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
type string Yes نوع data که قصد دریافت آن را دارید مشخص می‌کند که می‌تواند یکی از مقادیر: setting, meta, custom, high_score باشد.
Response
Status code Response Description
200 {"type":"high_score","data":{"value":123}} { "type": "custom", "data": {"player_achivement" : "10 point"} } بطور مثال، بالاترین امتیاز یک کاربر در قالب یک آرایه json برای شما ارسال می‌شود.
400 {"error": "Invalid data passed: type"} پارامتر type ارسال نشده است.
دریافت جدول نفرات برتر بازی

برای دریافت جدول قهرمانان بازی که قبلا امتیاز های آنان را با استفاده از تابع gameData ذخیره کرده‌اید، باید پارامترهای ذیل را بصورت POST به https://api.gap.im/leaderBoard به همراه توکن ارسال نمایید.

مقادیر ارسالی:
Parameter Type Required Description
chat_id integer Yes شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
time string Yes در صورتیکه تمایل دارید گزارش خود را به یک بازه زمانی خاص محدود کنید می توانید این پارامتر را با مقادیر all, month, day و week ارسال کنید. در غیر این صورت گزارش محدوده زمانی خاصی را شامل نمی شود.
Response
Status code Response Description
200 یک آرایه json شامل جزئیات مربوط به جدول قهرمانان، اطلاعات مربوط به کاربر جاری و همچنین اطلاعات مربوط به کاربرانی که به لحاظ امتیاز در همسایگی کاربر جاری قرار گرفته اند. این اطلاعات شامل نام، نام کاربری، امتیاز، آواتار و رتبه بازیکنان می باشد.
400 {"error": "Invalid data passed: time"} مقدار ارسالی برای پارامتر time نامعتبر است.

نمونه خروجی موفق:

[
	{
    "topLeaders": [
        {
            "nickname": "ali",
            "username": "hosseini",
            "avatar": "",
            "score": 80,
            "rank": 1
        },
        .....,
        {
            "nickname": "zahra",
            "username": "hashemi",
            "avatar": "",
            "score": 40,
            "rank": 3,
            "current_user": true
        },
       .....
    ],
    "currentPlayer": {
        "nickname": "zahra",
        "username": "hashemi",
        "avatar": "",
        "score": 40,
        "rank": 3
    },
    "nearBy": [
        {
            "nickname": "ali",
            "username": "hosseini",
            "avatar": "",
            "score": 80,
            "rank": 1
        },
        .....,
        {
            "nickname": "zahra",
            "username": "hashemi",
            "avatar": "",
            "score": 40,
            "rank": 3,
            "current_user": true
        },
        {
            "nickname": "n.a",
            "username": "",
            "avatar": "",
            "score": 10,
            "rank": 4
        },
        .....
    ]
}
]
دریافت اطلاعات مربوط به پیکربندی بازی

برای دریافت اطلاعات مربوط به پیکربندی بازی، باید پارامترهای ذیل را بصورت POST به https://api.gap.im/getGameConfig به همراه توکن ارسال نمایید.

قابل ذکر است اطلاعات مربوط به پیکربندی بازی را می توانید از طریق پورتال کسب و کار و بخش دنیای بازی ثبت کنید.

مقادیر ارسالی:
Parameter Type Required Description
key string No در صورتیکه مایل به دریافت پیکربندی خاصی از بازی هستید آن را در این فیلد ارسال کنید. در غیر این صورت همه موارد برای شما ارسال خواهد شد.
Response
Status code Response Description
200 {"configs": [{"key": "max_coin","value": "50"}]} به طور مثال، اگر key را مقدار max_coin ارسال کرده باشید مقدار مربوط به این key برای شما ارسال خواهد شد.
ثبت رخدادهای بازی

برای ثبت رخدادهای بازی می توانید پارامترهای ذیل را به صورت POST به https://api.gap.im/gameEvent به همراه توکن ارسال نمایید.

قابل ذکر است مزیت ثبت رخدادهای بازی برای شما این است که می توانید گزارشات آماری بازی خود بر اساس این رخدادها، مثلا گزارش فعالیت کاربر را در پورتال کسب و کار و در بخش دنیای بازی مشاهده کنید.

مقادیر ارسالی:
Parameter Type Required Description
event string Yes نام یک رخداد مربوط به بازی است . اگر مقدار این پارامتر برابر open باشد از آن برای محاسبه ی گزارش فعالیت روزانه، هفتگی و ماهانه کاربران استفاده می شود. در غیر این صورت هر رخداد دیگر بازی را می توانید ثبت کنید. توجه داشته باشید حداکثر تعداد رخدادهای قابل ثبت برای یک بازی ۲۵ است.
value string No در صورت تمایل می توانید برای هر رخداد مقدار مربوط به آن را نیز ارسال کنید. حداکثر سایز این پارامتر می تواند ۱ کیلو بایت باشد.
Response
Status code Response Description
200 مقادیر ارسالی با موفقیت ذخیره شده است.
400 {"error": "Invalid data passed: event"} پارامتر event ارسال نشده است.
400 {"error": "max size of event value is 1KB"} سایز دیتای ارسالی از حداکثر قابل قبول بیشتر است.
400 {"error": "max number of event is 25"} تعداد رخدادهای بازی از حداکثر قابل قبول بیشتر است.
نکات مهم در مورد API گیم سنتر گپ:
  • برای ذخیره بهترین امتیاز بازیکن تا این لحظه و ذخیره آن در سرور و نمایش در جدول نفرات برتر، فقط باید از type با مقدار high_score استفاده شود، در غیر این صورت در جدول نفرات برتر نمایش داده نمی شود. امتیاز فقط باید بصورت int ارسال شود.
  • هر نوع داده ای را می توانید به gameData ارسال کنید، مثلا اگر قصد دارید دارایی‌های کاربر مثل سکه را ذخیره کنید، type را برابر coin و data را مقدار سکه بازیکن قرار دهید.
  • شما می‌توانید در بخش data از ساختارهایی مثل json برای ذخیره پیشرفت بازیکن و... استفاده کنید. مثلا یک type به عنوان progress با دیتای لیست مرحله‌هایی که توسط بازیکن تمام شده رو به صورت json ذخیره و بازیابی کنید.
  • این اطلاعات برای هر بازیکن به صورت یونیک ذخیره می‌شود و نیازی نیست user_id یا مقداری به این عنوان در ورودی ثبت کنید و می‌توانید از chat_id به عنوان user_id داخل بازی استفاده کنید.
  • امتیازی که بصورت high_score ذخیره می‌شود، نمی‌تواند از امتیاز قبلی که برای این کاربر ذخیره شده کمتر باشد مگر اینکه پارامتر force را با مقدار true ارسال کنید.