api پیام رسان گپ

shape
shape
shape
shape
shape
shape
shape
shape

در این مطلب در مورد معرفی api پیام رسان گپ توضیح خواهیم داد.

معرفی

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

چه کارهایی می توانید انجام دهید

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

یک مثال ساده

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

پنل توسعه دهندگان

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

https://developer.gap.im

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

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

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

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

ایجاد سرویس جدید

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

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

دریافت TOKEN

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

کار با api

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

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

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

دریافت اطلاعات

‍‍POST <مسیر وارد شده در زمان ایجاد سرویس>

نام داده نوع توضیحات
chat_id integer یک شناسه ایجاد شده که برای ارتباط سرویس با یک کاربر از آن استفاده می شود.
type string می تواند شامل [join, text, image, video, audio, file, voice, triggerButton, invoiceCallback, payCallback, submitForm] باشد و نوع داده ارسالی کاربر را مشخص می‌کند.
data string محتوای داده‌ی ارسالی کاربر.
chat_id : این مقدار برای هر کاربر به ازای هر سرویس منحصربفرد می‌باشد باید توسط برنامه شما ذخیره شود تا برای پاسخ به کاربر بتوانید از آن استفاده کنید.
type : این مشخصه دارای مقادیری خاصی می‌باشد که هر کدام از این مقادیر نشانگر یک عملیات خاص می‌باشد.
توضیحات مقدار ارسالی Type
join این مقدار زمانی ارسال می شود که کاربر جدیدی عضو سرویس شود .
text / image / video / audio / file / voice در زمان ارسال یک پیام توسط کاربر در سرویس بسته به نوع پیام (متنی ، مدیا و…) مقدار type برابر با یکی از این مقادیر خواهد بود .
triggerButton این مقدار زمانی ارسال خواهد شد که کاربر بروی Inline Button که قبلا از نوع cb_data ایجاد کرده اید کلیک کند .
invoiceCallback این مقدار در زمان در زمانی که یک کاربر صورتحساب که توسط توسعه دهنده برای او ارسال شده را به با موفقیت پرداخت کند و یا خطایی در پروسه پرداخ رخ دهد ، ارسال خواهد شد . اطلاعات بیشتر در پرداخت صورتحساب .
payCallback این مقدار همانند invoiceCallback مربوط به بخش مالی می باشد و در زمانی که پرداخت درون برنامه ای با موفقیت انجام شود و یا خطایی رخ دهد برای توسعه دهنده ارسال خواهد شد . اطلاع بیشتر در پرداخت درون برنامه ای
submitForm زمانی که فرمی توسط توسعه دهنده برای کاربر ارسال می شود و کاربر آن را پر می کند و فرم را ارسال می کند پیام رسان گپ درخواستی به سمت توسعه دهنده ارسال می کند که مقدار type آن برابر با این و اطلاعات پر شده فرم در داخل پارامتر data موجود می باشد .

ارسال اطلاعات به کاربر

POST https://api.gap.im/sendMessage

نام داده نوع الزامی توضیحات
chat_id integer بلی شناسه منحصربفرد کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است. البته با در اختیار داشتن شماره موبایل کاربر که عضو سرویس شما می‌باشد می‌توانید در این فیلد بجای chat_id شماره موبایل کاربر را با فرمت 989123456789+ وارد کنید.
type string بلی نوع داده ارسال [text, image, video, audio, file, contact]
data string بلی متن و یا محتوای ارسالی شما
reply_keyboard string خیر افزودن کیبورد از نوع reply به پیام . این آرایه باید به صورت encode شده ارسال شود
inline_keyboard string خیر افزودن کیبورد از نوع inline به پیام . این آرایه باید به صورت encode شده ارسال شود
form string خیر ارسال فرم به کاربر . این آرایه باید به صورت encode شده ارسال شود

 

200 Success Request

توضیحات پارامتر
id شناسه پیام ارسالی شما . در واقع همان message_id می باشد .

 

Error 400 Bad Request

توضیحات پارامتر
chat_id داده ارسالی معتبر نمی‌باشد.
data داده ارسالی معتبر نمی‌باشد.
reply_keyboard داده ارسالی معتبر نمی‌باشد.
inline_keyboard داده ارسالی معتبر نمی‌باشد.

 

Error 403 Forbidden

توضیحات پارامتر
token Token ارسالی معتبر نمی باشد.

Chat ID

مقدار chat_id در انواع سرویس‌های مختلف به شرح ذیل است.
نوع سرویس نوع ارسال توضیحات
تعاملی – شناسه منحصربفرد کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است. البته با در اختیار داشتن شماره موبایل کاربر که عضو سرویس شما می‌باشد می‌توانید در این فیلد بجای chat_id شماره موبایل کاربر را با فرمت 989123456789+ وارد کنید.
اطلاع رسانی فردی شناسه منحصربفرد کاربر که در هنگام عضویت در سرویس و یا ارسال پیام برای توسعه دهنده ارسال شده است. البته با در اختیار داشتن شماره موبایل کاربر که عضو سرویس شما می‌باشد می‌توانید در این فیلد بجای chat_id شماره موبایل کاربر را با فرمت 989123456789+ وارد کنید.
اطلاع رسانی گروهی شناسه سرویس به همراه @ مثال: service@

نکته: شناسه کاربران به ازای هر سرویس مقداری منحصربفرد است.

ارسال فایل به کاربر

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

همچنین امکان ارسال های زیر نیز وجود دارد

ارسال شماره تلفن

ارسال موقعیت

ارسال تصویر

ارسال فایل صوتی

ارسال ویدئو

ارسال صدا و…

که کلیه مستندات لازم موجود می باشد .

ارسال صورت حساب

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

کتابخانه PHP کار با API

دریافت کتابخانه

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

نمونه کد NODE.js کار با API

دریافت کدها

در صورتی که می خواهید از nodejs برای برنامه خود و ارتباط با api گپ استفاده کنید می توانید از پکیج ایجاد شده برای راحتی کار با api که در مخازن npm موجود می باشد ، استفاده کنید .

در ان مطلب در مورد معرفی api پیام رسان گپ توصیح دادیم در مطلب بعد در مورد ابزار های کاربردی گپ بااستفاده از api توضیح خواهیم داد.

منبع

دیدگاهتان را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *