Bot Platform API

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 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

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

Basic Description

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

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

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

Receive messages from robot users

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

Sending information to the user

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

{
	"name":"Ehsan Sabet",
	"phone":"+989356167766"
}

{
	"lat":"36.297611661967245",
	"long":"59.602204039692886",
	"desc":""
}

{
	"data":"name=Ehsan&married=y&city=mashhad&address=Iran&agree=true",
	"message_id":97,
	"callback_id":"N7YcI5rAlX2sEFmh"
}

{
	"data":"yes",
	"message_id":98,
	"callback_id":"XoXN/QCEMd4JeICk"
}

{
	"ref_id":"123456",
	"message_id":"99",
	"status":"success"
}

{
	"invoiceId":"5bcd7f7ca74ad8015d65205d"
}

توکن ربات (Token)

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

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

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

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

chat_id

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

انواع ارسال پیام ربات به کاربر

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

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

[
	[
		{
		"text":"پرداخت سکه",
		"amount":2,
		"currency":"coin",
		"ref_id":"XXXXXXX",
		"desc":"توضیحات مربوط به پرداخت برای نمایش در لیست تراکنش ها"
		}
	]
]

انواع Keyboard

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

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

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

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

[
	[
		{
			"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":"توضیحات مربوط به پرداخت برای نمایش در لیست تراکنش ها"
		}
	]
]

ارسال فرم به کاربر:

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

[
	{
		"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 ارایه شده ذخیره و یا بازیابی کنید. همچنین با استفاده از اطلاعاتی که ارسال کرده اید، جدول بازی‌ را در بازه های زمانی مختلف دریافت و به کاربران نمایش دهید.

[
	{
    "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
        },
        .....
    ]
}
]