مستندات
فارسی

Bot Platform API

مقدمه

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

چه کارهایی می توانید انجام دهید
  • ارسال پیام به هر یک از کاربران عضو شده در ربات (از طریق شناسه و یا شماره موبایل)
  • ارسال پیام ساده و چند رسانه ای (متن ، تصویر ، ویدئو و صدا و . . . )
  • دریافت پیام های ارسالی کاربران
  • ارائه گزینه های قابل انتخاب برای کاربران (Reply keyboard)
  • امکان دریافت وجه از مخاطب (Payment API)
یک مثال ساده

یک ربات هواشناسی را فرض کنید که کاربران با ارسال نام شهر قصد دارند از وضعیت آب و هوای چند روز آینده آن شهر مطلع شوند . برای این کار کافیست کاربران اسم شهر مورد نظر را در ربات شما ارسال کنند و شما در برنامه خود و با استفاده از API توسعه دهندگان پس از دریافت نام شهر وضعیت آب و هوای آن را از طریق سایت های هواشناسی پیدا کرده و سپس به شکل متن یا تصویر برای کاربر ارسال کنید.

انواع ربات‌ها

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

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

شروع کار

بات پلتفرم

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

https://my.gap.im

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

رمز یکبار مصرف

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

ورود به وسیله کد QR

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

ایجاد ربات جدید

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

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

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

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

دریافت TOKEN

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

کار با API

توضیحات اولیه

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

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

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

دریافت پیام‌های کاربران ربات

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

پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
from string یک آرایه از نوع json که شامل id، name و username کاربر عضو شده در ربات می‌باشد.
type string نوع داده ارسالی کاربر را مشخص می‌کند.
data string محتوای داده‌ی ارسالی کاربر.
انواع پیام‌های ارسالی کاربر به ربات

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

عضویت کاربر:
پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
type string نوع داده ارسالی کاربر را مشخص می‌کند. که در این نوع پیام مقدار ثابت join است.
لغو عصویت کاربر:
پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
type string نوع داده ارسالی کاربر را مشخص می‌کند. که در این نوع پیام مقدار ثابت leave است.
دریافت پیام متنی:
پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
type string نوع داده ارسالی کاربر را مشخص می‌کند. که در این نوع پیام مقدار ثابت text است.
from string یک آرایه از نوع json که شامل id، name و username کاربر عضو شده در ربات می‌باشد.
data string محتوای داده‌ی ارسالی کاربر.
دریافت تصویر:
پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
type string نوع داده ارسالی کاربر را مشخص می‌کند. که در این نوع پیام مقدار ثابت image است.
from string یک آرایه از نوع json که شامل id، name و username کاربر عضو شده در ربات می‌باشد.
data string یک آرایه از نوع json می‌باشد که شامل اطلاعات فایل image است.
دریافت فایل صوتی:
پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
type string نوع داده ارسالی کاربر را مشخص می‌کند. که در این نوع پیام مقدار ثابت audio است.
from string یک آرایه از نوع json که شامل id، name و username کاربر عضو شده در ربات می‌باشد.
data string یک آرایه از نوع json می‌باشد که شامل اطلاعات فایل audio است.
دریافت ویدیو:
پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
type string نوع داده ارسالی کاربر را مشخص می‌کند. که در این نوع پیام مقدار ثابت video است.
from string یک آرایه از نوع json که شامل id، name و username کاربر عضو شده در ربات می‌باشد.
data string یک آرایه از نوع json می‌باشد که شامل اطلاعات فایل video است.
دریافت صدا:
پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
type string نوع داده ارسالی کاربر را مشخص می‌کند. که در این نوع پیام مقدار ثابت voice است.
from string یک آرایه از نوع json که شامل id، name و username کاربر عضو شده در ربات می‌باشد.
data string یک آرایه از نوع json می‌باشد که شامل اطلاعات فایل voice است.
دریافت فایل:
پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
type string نوع داده ارسالی کاربر را مشخص می‌کند. که در این نوع پیام مقدار ثابت file است.
from string یک آرایه از نوع json که شامل id، name و username کاربر عضو شده در ربات می‌باشد.
data string یک آرایه از نوع json می‌باشد که شامل اطلاعات file است.
دریافت شماره تلفن:
پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
type string نوع داده ارسالی کاربر را مشخص می‌کند. که در این نوع پیام مقدار ثابت contact است.
from string یک آرایه از نوع json که شامل id، name و username کاربر عضو شده در ربات می‌باشد.
data string یک آرایه از نوع json می‌باشد که شامل اطلاعات contact است.

مثال: مقدار data در هنگام دریافت contact از طرف کاربر:

{
	"name":"Ehsan Sabet",
	"phone":"+989356167766"
}
دریافت موقعیت جغرافیایی:
پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
type string نوع داده ارسالی کاربر را مشخص می‌کند. که در این نوع پیام مقدار ثابت location است.
from string یک آرایه از نوع json که شامل id، name و username کاربر عضو شده در ربات می‌باشد.
data string یک آرایه از نوع json می‌باشد که شامل اطلاعات location است.

مثال: مقدار data در هنگام دریافت location از طرف کاربر:

{
	"lat":"36.297611661967245",
	"long":"59.602204039692886",
	"desc":""
}
دریافت فرم:
پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
type string نوع داده ارسالی کاربر را مشخص می‌کند. که در این نوع پیام مقدار ثابت submitForm است.
from string یک آرایه از نوع json که شامل id، name و username کاربر عضو شده در ربات می‌باشد.
data string یک آرایه از نوع json می‌باشد که شامل اطلاعات form است.

مثال: مقدار data در هنگام دریافت submitForm از طرف کاربر:

{
	"data":"name=Ehsan&married=y&city=mashhad&address=Iran&agree=true",
	"message_id":97,
	"callback_id":"N7YcI5rAlX2sEFmh"
}
دریافت اطلاعات هنگام کلیک روی دکمه‌ inline دارای cb_data توسط کاربر:
پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
type string نوع داده ارسالی کاربر را مشخص می‌کند. که در این نوع پیام مقدار ثابت triggerButton است.
from string یک آرایه از نوع json که شامل id، name و username کاربر عضو شده در ربات می‌باشد.
data string یک آرایه از نوع json می‌باشد که شامل اطلاعات trigger button است.

مثال: مقدار data در هنگام دریافت triggerButton از طرف کاربر:

{
	"data":"yes",
	"message_id":98,
	"callback_id":"XoXN/QCEMd4JeICk"
}
اطلاعات پرداخت:
پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
type string نوع داده ارسالی کاربر را مشخص می‌کند. که در این نوع پیام مقدار ثابت paycallback است.
from string یک آرایه از نوع json که شامل id، name و username کاربر عضو شده در ربات می‌باشد.
data string یک آرایه از نوع json می‌باشد که شامل اطلاعات payment است.

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

مثال: مقدار data در هنگام دریافت paycallback از طرف کاربر:

{
	"ref_id":"123456",
	"message_id":"99",
	"status":"success"
}
اطلاعات صورتحساب:
پارامتر نوع توضیحات
chat_id integer شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر از آن استفاده می‌شود.
type string نوع داده ارسالی کاربر را مشخص می‌کند. که در این نوع پیام مقدار ثابت invoicecallback است.
from string یک آرایه از نوع json که شامل id، name و username کاربر عضو شده در ربات می‌باشد.
data string یک آرایه از نوع json می‌باشد که شامل اطلاعات invoice است.

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

مثال: مقدار data در هنگام دریافت invoicecallback از طرف کاربر:

{
	"invoiceId":"5bcd7f7ca74ad8015d65205d"
}

توکن ربات (Token)

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

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

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

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

chat_id

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

مقدار chat_id در انواع ربات‌ها:
پارامتر نوع پارامتر نوع نحوه ارسال توضیحات
chat_id integer ربات تعاملی - شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
string شماره موبایل کاربر عضو شده در ربات با فرمت +989123456789
integer ربات اطلاع رسانی فردی شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
string شماره موبایل کاربر عضو شده در ربات با فرمت +989123456789
string گروهی شناسه ربات به همراه @ بطور مثال: @bot
انواع ارسال پیام ربات به کاربر
ارسال پیام متنی (Text) به کاربر:
پارامتر نوع توضیحات
chat_id integer / string توضیحات مربوط به chat_id
type string نوع داده ارسالی را مشخص می‌کند. که در این نوع پیام مقدار ثابت text است.
data string متن و یا محتوای ارسالی شما
reply_keyboard string افزودن کیبورد از نوع reply به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به reply_keyboard )
inline_keyboard string افزودن کیبورد از نوع inline به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به inline_keyboard )
form string افزودن form به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به form)
خروجی
کد وضعیت خروجی توضیحات
200 {"id": 1333} مقدار id، همان message_id پیام ارسال شده برای کاربر می‌باشد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: type"} محتوای پارامتر type معتبر نمی‌باشد.
400 {"error":"Invalid data passed: data"} محتوای پارامتر data معتبر نمی‌باشد.
400 {"error":"Invalid data passed: reply_keyboard"} محتوای پارامتر reply_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: inline_keyboard"} محتوای پارامتر inline_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: form"} محتوای پارامتر form معتبر نمی‌باشد.
ارسال تصویر (Image) به کاربر:
پارامتر نوع توضیحات
chat_id integer / string توضیحات مربوط به chat_id
type string نوع داده ارسالی را مشخص می‌کند. که در این نوع پیام مقدار ثابت image است.
data string خروجی متود آپلود که بصورت JSON است. (آپلود)
reply_keyboard string افزودن کیبورد از نوع reply به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به reply_keyboard )
inline_keyboard string افزودن کیبورد از نوع inline به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به inline_keyboard )
form string افزودن form به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به form)

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

خروجی
کد وضعیت خروجی توضیحات
200 {"id": 1333} مقدار id، همان message_id پیام ارسال شده برای کاربر می‌باشد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: type"} محتوای پارامتر type معتبر نمی‌باشد.
400 {"error":"Invalid data passed: data"} محتوای پارامتر data معتبر نمی‌باشد.
400 {"error":"Invalid data passed: reply_keyboard"} محتوای پارامتر reply_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: inline_keyboard"} محتوای پارامتر inline_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: form"} محتوای پارامتر form معتبر نمی‌باشد.
ارسال فایل صوتی (Audio) به کاربر:
پارامتر نوع توضیحات
chat_id integer / string توضیحات مربوط به chat_id
type string نوع داده ارسالی را مشخص می‌کند. که در این نوع پیام مقدار ثابت audio است.
data string خروجی متود آپلود که بصورت JSON است. (آپلود)
reply_keyboard string افزودن کیبورد از نوع reply به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به reply_keyboard )
inline_keyboard string افزودن کیبورد از نوع inline به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به inline_keyboard )
form string افزودن form به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به form)

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

خروجی
کد وضعیت خروجی توضیحات
200 {"id": 1333} مقدار id، همان message_id پیام ارسال شده برای کاربر می‌باشد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: type"} محتوای پارامتر type معتبر نمی‌باشد.
400 {"error":"Invalid data passed: data"} محتوای پارامتر data معتبر نمی‌باشد.
400 {"error":"Invalid data passed: reply_keyboard"} محتوای پارامتر reply_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: inline_keyboard"} محتوای پارامتر inline_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: form"} محتوای پارامتر form معتبر نمی‌باشد.
ارسال ویدیو (Video) به کاربر:
پارامتر نوع توضیحات
chat_id integer / string توضیحات مربوط به chat_id
type string نوع داده ارسالی را مشخص می‌کند. که در این نوع پیام مقدار ثابت video است.
data string خروجی متود آپلود که بصورت JSON است. (آپلود)
reply_keyboard string افزودن کیبورد از نوع reply به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به reply_keyboard )
inline_keyboard string افزودن کیبورد از نوع inline به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به inline_keyboard )
form string افزودن form به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به form)

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

خروجی
کد وضعیت خروجی توضیحات
200 {"id": 1333} مقدار id، همان message_id پیام ارسال شده برای کاربر می‌باشد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: type"} محتوای پارامتر type معتبر نمی‌باشد.
400 {"error":"Invalid data passed: data"} محتوای پارامتر data معتبر نمی‌باشد.
400 {"error":"Invalid data passed: reply_keyboard"} محتوای پارامتر reply_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: inline_keyboard"} محتوای پارامتر inline_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: form"} محتوای پارامتر form معتبر نمی‌باشد.
ارسال صدا (Voice) به کاربر:
پارامتر نوع توضیحات
chat_id integer / string توضیحات مربوط به chat_id
type string نوع داده ارسالی را مشخص می‌کند. که در این نوع پیام مقدار ثابت voice است.
data string خروجی متود آپلود که بصورت JSON است. (آپلود)
reply_keyboard string افزودن کیبورد از نوع reply به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به reply_keyboard )
inline_keyboard string افزودن کیبورد از نوع inline به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به inline_keyboard )
form string افزودن form به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به form)

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

خروجی
کد وضعیت خروجی توضیحات
200 {"id": 1333} مقدار id، همان message_id پیام ارسال شده برای کاربر می‌باشد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: type"} محتوای پارامتر type معتبر نمی‌باشد.
400 {"error":"Invalid data passed: data"} محتوای پارامتر data معتبر نمی‌باشد.
400 {"error":"Invalid data passed: reply_keyboard"} محتوای پارامتر reply_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: inline_keyboard"} محتوای پارامتر inline_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: form"} محتوای پارامتر form معتبر نمی‌باشد.
ارسال فایل (File) به کاربر:
پارامتر نوع توضیحات
chat_id integer / string توضیحات مربوط به chat_id
type string نوع داده ارسالی را مشخص می‌کند. که در این نوع پیام مقدار ثابت file است.
data string خروجی متود آپلود که بصورت JSON است. (آپلود)
reply_keyboard string افزودن کیبورد از نوع reply به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به reply_keyboard )
inline_keyboard string افزودن کیبورد از نوع inline به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به inline_keyboard )
form string افزودن form به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به form)

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

خروجی
کد وضعیت خروجی توضیحات
200 {"id": 1333} مقدار id، همان message_id پیام ارسال شده برای کاربر می‌باشد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: type"} محتوای پارامتر type معتبر نمی‌باشد.
400 {"error":"Invalid data passed: data"} محتوای پارامتر data معتبر نمی‌باشد.
400 {"error":"Invalid data passed: reply_keyboard"} محتوای پارامتر reply_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: inline_keyboard"} محتوای پارامتر inline_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: form"} محتوای پارامتر form معتبر نمی‌باشد.
ارسال شماره تلفن (Contact) به کاربر:
پارامتر نوع توضیحات
chat_id integer / string توضیحات مربوط به chat_id
type string نوع داده ارسالی را مشخص می‌کند. که در این نوع پیام مقدار ثابت contact است.
data string یک JSON که شامل کلیدهای phone و name است.
reply_keyboard string افزودن کیبورد از نوع reply به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به reply_keyboard )
inline_keyboard string افزودن کیبورد از نوع inline به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به inline_keyboard )
form string افزودن form به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به form)

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

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

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

خروجی
کد وضعیت خروجی توضیحات
200 {"id": 1333} مقدار id، همان message_id پیام ارسال شده برای کاربر می‌باشد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: type"} محتوای پارامتر type معتبر نمی‌باشد.
400 {"error":"Invalid data passed: data"} محتوای پارامتر data معتبر نمی‌باشد.
400 {"error":"Invalid data passed: reply_keyboard"} محتوای پارامتر reply_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: inline_keyboard"} محتوای پارامتر inline_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: form"} محتوای پارامتر form معتبر نمی‌باشد.
ارسال موقعیت جغرافیایی (Location) به کاربر:
پارامتر نوع توضیحات
chat_id integer / string توضیحات مربوط به chat_id
type string نوع داده ارسالی را مشخص می‌کند. که در این نوع پیام مقدار ثابت location است.
data string یک JSON که شامل کلیدهای lat، long و desc است.
reply_keyboard string افزودن کیبورد از نوع reply به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به reply_keyboard )
inline_keyboard string افزودن کیبورد از نوع inline به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به inline_keyboard )
form string افزودن form به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به form)

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

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

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

خروجی
کد وضعیت خروجی توضیحات
200 {"id": 1333} مقدار id، همان message_id پیام ارسال شده برای کاربر می‌باشد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: type"} محتوای پارامتر type معتبر نمی‌باشد.
400 {"error":"Invalid data passed: data"} محتوای پارامتر data معتبر نمی‌باشد.
400 {"error":"Invalid data passed: reply_keyboard"} محتوای پارامتر reply_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: inline_keyboard"} محتوای پارامتر inline_keyboard معتبر نمی‌باشد.
400 {"error":"Invalid data passed: form"} محتوای پارامتر form معتبر نمی‌باشد.
ارسال Action

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

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

ارسال Action به کاربر:
پارامتر نوع توضیحات
chat_id integer / string توضیحات مربوط به chat_id
type string نوع action ارسالی را مشخص می‌کند، که در حال حاضر فقط یک نوع action پشتیبانی می‌شود. و مقدار آن باید برابر با typing باشد.
خروجی
کد وضعیت خروجی توضیحات
200 Action با موفقیت برای کاربر ارسال شده است.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: type"} محتوای پارامتر type معتبر نمی‌باشد.
آپلود فایل

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

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

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

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

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

ویرایش پیام ارسال شده به کاربر:
پارامتر نوع الزامی توضیحات
chat_id integer / string بله توضیحات مربوط به chat_id
message_id integer بله message_id پیامی که قصد ویرایش آن را دارید.
data string بله متن جدیدی که قصد ارسال آن را دارید.
inline_keyboard string خیر افزودن کیبورد از نوع inline به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به inline_keyboard )
خروجی
کد وضعیت خروجی توضیحات
200 - پیام با موفقیت ویرایش شد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: message_id"} محتوای پارامتر message_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: inline_keyboard"} محتوای پارامتر inline_keyboard معتبر نمی‌باشد.
حذف پیام‌های ارسال شده به کاربران

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

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

حذف پیام ارسال شده به کاربر:
پارامتر نوع الزامی توضیحات
chat_id integer / string بله توضیحات مربوط به chat_id
message_id integer بله message_id پیامی که قصد حذف آن را دارید.
خروجی
کد وضعیت خروجی توضیحات
200 - پیام با موفقیت حذف شد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: message_id"} محتوای پارامتر message_id معتبر نمی‌باشد.
Answer Callback

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

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

ارسال Answer Callback به کاربر:
پارامتر نوع الزامی توضیحات
chat_id integer بله شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
callback_id integer بله آی‌دی دکمه کلیک شده توسط کاربر، که هنگام کلیک بصورت triggerButton برای برنامه توسعه دهنده ارسال می‌شود.
text string بله متن پیامی که قصد نمایش آن به کاربر را دارید.
show_alert boolean بله نوع نمایش پیغام به کاربر را مشخص می‌کند که در صورت true بودن پیام به صورت alert و در صورت وجود مقدار false به شکل tooltip نمایش داده خواهد شد .
خروجی
کد وضعیت خروجی توضیحات
200 - پیغام با موفقیت ارسال شد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
ارسال صورتحساب برای کاربر

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

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

ارسال صورتحساب:
پارامتر نوع الزامی توضیحات
chat_id integer بله شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
amount integer بله مبلغ صورتحساب که کاربر باید پرداخت کند.
currency string خیر این مقدار مشخص کننده واحد پولی صورتحساب است که می‌توانید یکی از مقادیر IRR (ریال) و یا USD (دلار) را وارد کنید. اگر این مقدار وارد نشود بطور پیشفرض صورتحساب ریالی صادر خواهد شد.
description string بله توضیحات مربوط به صورتحساب پرداختی که به کاربر نمایش داده می‌شود.
expire_time integer خیر مدت زمان اعتبار صورتحساب بر حسب ثانیه است. مقدار پیشفرض این فیلد 86400 ثانیه (یک روز) است. حداقل مقدار قابل قبول این فیلد 300 (معادل پنج دقیقه) و حداکثر 604800 (معادل یک هفته) می‌باشد.

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

خروجی
کد وضعیت خروجی توضیحات
200 {"id":"5bd04ea7a74ad805f8045b91"} مقدار id، همان invoice_id صورتحساب ارسال شده برای کاربر می‌باشد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: amount"} محتوای پارامتر amount معتبر نمی‌باشد.
تایید صورتحساب

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

تایید صورتحساب:
پارامتر نوع الزامی توضیحات
chat_id integer بله شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
ref_id string بله invoice_id که در هنگام ارسال صورتحساب دریافت کرده‌اید.
خروجی
کد وضعیت خروجی توضیحات
200 {"amount":10000,"status":"verified"} مقدار status، مشخص می‌کند که این صورتحساب پرداخت و تایید شده است و مقدار آن را نمایش می‌دهد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
405 - مقدار ref_id معتبر نمی‌باشد.
استعلام صورتحساب

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

استعلام صورتحساب:
پارامتر نوع الزامی توضیحات
chat_id integer بله شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
ref_id string بله invoice_id که در هنگام ارسال صورتحساب دریافت کرده‌اید.
خروجی
کد وضعیت خروجی توضیحات
200 {"status":"error"} مقدار status، مشخص می‌کند که این صورتحساب پرداخت نشده است و یا ref_id اشتباه است.
200 {"amount":10000,"status":"verified"} مقدار status، مشخص می‌کند که این صورتحساب پرداخت شده است و مقدار آن را نمایش می‌دهد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: ref_id"} محتوای پارامتر ref_id معتبر نمی‌باشد.
پرداخت درون برنامه‌ای

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

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

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

ایجاد دکمه پرداخت درون برنامه‌ای:
پارامتر نوع الزامی توضیحات
chat_id integer / string بله توضیحات مربوط به chat_id
type string بله نوع داده ارسالی را مشخص می‌کند. که در این نوع پیام مقدار ثابت text است.
data string بله متن و یا محتوای ارسالی شما
inline_keyboard string بله افزودن کیبورد از نوع inline حاوی دکمه پرداخت درون برنامه‌ای به پیام. این مقدار باید به صورت JSON ارسال شود. (توضیحات مربوط به inline_keyboard)

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

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

[
	[
		{
		"text":"پرداخت سکه",
		"amount":2,
		"currency":"coin",
		"ref_id":"XXXXXXX",
		"desc":"توضیحات مربوط به پرداخت برای نمایش در لیست تراکنش ها"
		}
	]
]
خروجی
کد وضعیت خروجی توضیحات
200 {"id": 1333} مقدار id، همان message_id پیام ارسال شده برای کاربر می‌باشد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: type"} محتوای پارامتر type معتبر نمی‌باشد.
400 {"error":"Invalid data passed: data"} محتوای پارامتر data معتبر نمی‌باشد.
400 {"error":"Invalid data passed: inline_keyboard"} محتوای پارامتر inline_keyboard معتبر نمی‌باشد.
تایید پرداخت درون برنامه‌ای

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

تایید پرداخت درون برنامه‌ای:
پارامتر نوع الزامی توضیحات
chat_id integer بله شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
ref_id string بله ref_id که در هنگام ایجاد دکمه پرداخت درون برنامه‌ای توسط توسعه دهنده تولید شده است.
خروجی
کد وضعیت خروجی توضیحات
200 {"amount":2,"status":"verified"} مقدار status، مشخص می‌کند که این پرداخت درون برنامه‌ای انجام و تایید شده است و مقدار آن را نمایش می‌دهد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
405 - مقدار ref_id معتبر نمی‌باشد.
استعلام پرداخت درون برنامه‌ای

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

استعلام پرداخت درون برنامه‌ای:
پارامتر نوع الزامی توضیحات
chat_id integer بله شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
ref_id string بله ref_id که در هنگام ایجاد دکمه پرداخت توسط توسعه دهنده تولید شده است.
خروجی
کد وضعیت خروجی توضیحات
200 {"status":"error"} مقدار status، مشخص می‌کند که این پرداخت درون برنامه‌ای انجام نشده است و یا ref_id اشتباه است.
200 {"amount":2,"status":"verified"} مقدار status، مشخص می‌کند که این پرداخت انجام شده است و مقدار آن را نمایش می‌دهد.
403 - توکن و یا پارامتر chat_id معتبر نمی‌باشد.
400 {"error":"Invalid data passed: ref_id"} محتوای پارامتر ref_id معتبر نمی‌باشد.

انواع 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 نوع الزامی توضیحات
text string بله متن دکمه که برای کاربر نمایش داده می‌شود.
cb_data string خیر هنگام کلیک بروی این دکمه، سرور یک درخواست از نوع triggerButton به سمت برنامه توسعه دهنده ارسال خواهد کرد که شامل مقدار cb_data می‌باشد.
url string خیر هنگام کلیک بروی این دکمه، مسیری که در مقابل این پارامتر قرار دارد در مرورگر کاربر باز خواهد شد.
open_in string خیر اگر دکمه‌ای که ساخته شده دارای مقدار url باشد، شما میتوانید نحوه بازشدن این لینک را مشخص کنید.
مقدار این key می‌تواند یک از این موارد باشد: browser, inline_browser, webview_full, webview_with_header, webview
amount integer خیر این مقدار به منظور گرفتن وجه از کاربر به شکل پرداخت درون برنامه‌ای می‌باشد.
currency string خیر این مقدار مشخص کننده واحد پول است. که در حال حاضر می‌تواند برای پرداخت‌های ریالی مقدار IRR و پرداخت گپسی مقدار coin را دریافت کند.
در صورت ارسال amount، ارسال این مقدار نیز الزامی است.
ref_id string خیر یک رشته Base64 شامل حروف و ارقام می‌باشد.
در صورت ارسال amount، ارسال این مقدار نیز الزامی است.
desc string خیر توضیحات مربوط به پرداخت که برای نمایش در لیست تراکنش‌ها استفاده می‌شود.
در صورت ارسال 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
نام توضیحات
name نام منحصر به فرد برای هر فیلد.
type نوع فیلد فرم که می‌تواند با یکی از مقادیر [text ,radio ,select ,textarea ,checkbox ,inbuilt ,submit] پر شود.
label نام نمایشی جلوی هر فیلد در فرم.
options زمانی که مقدار پارامتر type برابر با یکی از مقادیر [select ,radio] باشد می‌توانید گزینه‌های قابل انتخاب توسط کاربر را در این پارامتر مشخص کنید.
انواع فیلدهای قابل استفاده در form
نوع توضیحات
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 به همراه توکن ارسال نمایید.

مقادیر ارسالی:
پارامتر نوع الزامی توضیحات
chat_id integer بله شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
type string بله نوع data ارسالی را مشخص می‌کند، به منظور ذخیره ی امتیاز بازیکن این پارامتر را برابر high_score قرار دهید و در غیر این صورت هر نوع دیگری مختص به بازی خود را می توانید ارسال کنید. ذکر این نکته الزامی است که شما حداکثر قادر به ارسال ۲۵ type متفاوت هستید.
data string بله مقداری که قصد ذخیره کردن آن را دارید در این قسمت قرار می‌گیرد. توجه داشته باشید که اگر type مورد نظر high_score است این مقدار حتما باید integer باشد و در غیر این صورت می تواند هر نوع داده ای را شامل شود . حداکثر سایز قابل قبول برای این پارامتر ۱۰ کیلوبایت است.
force Boolean خیر این پارامتر برای نوع داده ای high_score مورد استفاده قرار می گیرد و به صورت پیش فرض false است و چنانچه امتیاز فعلی از امتیاز قبلی کمتر باشد سرور آن را ذخیره نمی کند. اگر بنا به هرعلتی اعم از رخداد اشتباه یا تقلب تمایل به ذخیره ی امتیاز کمتر دارید این پارمتر را با مقدار true ارسال کنید.
خروجی
کد وضعیت خروجی توضیحات
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 به همراه توکن ارسال نمایید.

مقادیر ارسالی:
پارامتر نوع الزامی توضیحات
chat_id integer بله شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
type string بله نوع data که قصد دریافت آن را دارید مشخص می‌کند که می‌تواند high_score یا سایر مقادیری باشد که قبلا در قسمت ذخیره اطلاعات بازیکن ارسال کرده‌اید.
خروجی
کد وضعیت خروجی توضیحات
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 به همراه توکن ارسال نمایید.

مقادیر ارسالی:
پارامتر نوع الزامی توضیحات
chat_id integer بله شناسه منحصربفرد کاربر عضو شده در ربات، که برای ارتباط ربات با آن کاربر استفاده می‌شود.
time string بله در صورتیکه تمایل دارید گزارش خود را به یک بازه زمانی خاص محدود کنید می توانید این پارامتر را با مقادیر all, month, day و week ارسال کنید. در غیر این صورت گزارش محدوده زمانی خاصی را شامل نمی شود.
خروجی
کد وضعیت خروجی توضیحات
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 به همراه توکن ارسال نمایید.

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

مقادیر ارسالی:
پارامتر نوع الزامی توضیحات
key string خیر در صورتیکه مایل به دریافت پیکربندی خاصی از بازی هستید آن را در این فیلد ارسال کنید. در غیر این صورت همه موارد برای شما ارسال خواهد شد.
خروجی
کد وضعیت خروجی توضیحات
200 {"configs": [{"key": "max_coin","value": "50"}]} به طور مثال، اگر key را مقدار max_coin ارسال کرده باشید مقدار مربوط به این key برای شما ارسال خواهد شد.
ثبت رخدادهای بازی

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

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

مقادیر ارسالی:
پارامتر نوع الزامی توضیحات
event string بله نام یک رخداد مربوط به بازی است . اگر مقدار این پارامتر برابر open باشد از آن برای محاسبه ی گزارش فعالیت روزانه، هفتگی و ماهانه کاربران استفاده می شود. در غیر این صورت هر رخداد دیگر بازی را می توانید ثبت کنید. توجه داشته باشید حداکثر تعداد رخدادهای قابل ثبت برای یک بازی ۲۵ است.
value string خیر در صورت تمایل می توانید برای هر رخداد مقدار مربوط به آن را نیز ارسال کنید. حداکثر سایز این پارامتر می تواند ۱ کیلو بایت باشد.
خروجی
کد وضعیت خروجی توضیحات
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 ارسال کنید.