پایگاه دانش GetMyBot

کانال‌ها: Telegram، WhatsApp، VK

اتصال Telegram، WhatsApp و VK به یک پروژه؛ تفاوت امکانات کانال‌ها و مسیر بازگشت پاسخ بات.

در این صفحه

یک پروژهٔ GetMyBot می‌تواند در Telegram، WhatsApp و VK پاسخ دهد. برای مثال، می‌توانید یک واکنش مربوط به برنامهٔ کلاس‌ها را در هر سه پیام‌رسان به کار ببرید. پاسخ به همان کانالی برمی‌گردد که فرد از آن پیام فرستاده است.

هنگام اتصال پیام‌رسان دیگر، دکمه‌ها و اقدام‌ها را در آن امتحان کنید؛ امکانات پلتفرم‌ها یکسان نیست. تفاوت‌ها و روش اتصال در ادامه آمده است.

کانال چیست

کانال مسیر ارتباطی متصل به پروژه است: یک بات مشخص Telegram، شمارهٔ WhatsApp Business یا جامعهٔ VK. یک پروژهٔ GetMyBot می‌تواند چند کانال داشته باشد. واکنش‌ها مشترک‌اند: پیام مشترک WhatsApp با همان واکنش‌های Telegram پردازش می‌شود و پاسخ به WhatsApp برمی‌گردد.

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

کانال اصلی (primary_channel)

هر بات یک کانال اصلی (primary_channel) دارد، یعنی پلتفرمی که بات در آغاز با آن شناخته می‌شود. معمولاً Telegram است، اما می‌توانید بات را از ابتدا با WhatsApp یا VK، حتی بدون Telegram، بسازید. کانال اصلی هنگام ساخت تعیین می‌شود و در فهرست بات‌ها دیده می‌شود؛ کانال‌های دیگر بعداً اضافه می‌شوند.

جدول امکانات کانال‌ها

این بخش امکانات هر پیام‌رسان را توضیح می‌دهد. API نیز جدول به‌روز و قابل‌خواندن برای نرم‌افزار را از GET /api/channels/capabilities می‌دهد.

Telegram: دکمه‌های inline و صفحه‌کلید پاسخ، callback (فشار دکمه که واکنش را اجرا می‌کند)، واکنش ایموجی، پیوند /start، ویرایش، حذف و بازارسال پیام، پاسخ به پیام به‌عنوان محرک، رویدادهای اعضا، مجوزها و مدیریت اعضا. کارت‌های عکس در یک پیام ورق می‌خورند، به‌شرط آنکه برای همهٔ عکس‌ها file_id قابل‌استفاده وجود داشته باشد. قالب‌بندی متن: Plain / HTML / Markdown. قالب پیام WhatsApp، فهرست تعاملی و پنجرهٔ نشست ندارد.

WhatsApp از طریق WhatsApp Cloud API: دکمه‌های inline، callback، واکنش ایموجی، پیوند /start، قالب‌های پیام، فهرست‌های تعاملی (interactive list) و پنجرهٔ نشست ۲۴ ساعته. قالب‌بندی: Plain / Markdown. صفحه‌کلید پاسخ، ویرایش، حذف و بازارسال پیام، پاسخ به پیام به‌عنوان محرک، رویدادهای اعضا، مجوزهای مدیریتی و ورق زدن کارت‌ها در یک پیام را پشتیبانی نمی‌کند. بیشتر بخوانید: WhatsApp.

VK: پیام و پیوست، دکمه‌های inline و صفحه‌کلید پاسخ، callback، واکنش ایموجی، پیوند /start، ویرایش، حذف و بازارسال پیام، رویدادهای اعضا، مسدود و آزاد کردن کاربر، پذیرش درخواست عضویتِ ثبت‌شده در جامعهٔ بسته و رویدادهای اشتراک پولی VK Donut. قالب‌بندی فقط متن ساده است؛ HTML و Markdown هنگام نمایش حذف می‌شوند. قالب‌های WhatsApp، فهرست تعاملی، ورق زدن کارت‌ها در یک پیام و پنجرهٔ نشست ندارد.

همهٔ کانال‌ها از دکمهٔ inline، callback، واکنش ایموجی و پیوند /start پشتیبانی می‌کنند. بلوک کارت‌های عکس در کانال‌هایی که عکس می‌پذیرند در دسترس است. در Telegram، فقط وقتی همهٔ عکس‌ها file_id مناسب دارند، کارت‌ها در یک پیام ورق می‌خورند؛ در غیر این صورت مانند WhatsApp و VK، هر کارت به‌صورت پیام عکس جداگانه فرستاده می‌شود. پیام‌ها و دکمه‌ها را ببینید.

VK Donut

اگر VK Donut برای جامعه فعال باشد، بات این رویدادهای سیستمی اشتراک پولی را دریافت می‌کند:

رویداد در سازندهکلیدمتغیرهای قابل‌استفاده
VK Donut: subscription createddonut_subscription_created{{event.donut_amount}}، {{event.donut_amount_without_fee}}
VK Donut: subscription prolongeddonut_subscription_prolonged{{event.donut_amount}}، {{event.donut_amount_without_fee}}
VK Donut: subscription expireddonut_subscription_expiredندارد
VK Donut: subscription cancelleddonut_subscription_cancelledندارد

{{event.donut_amount}} مبلغ پرداخت و {{event.donut_amount_without_fee}} مبلغ بدون کارمزد VK است. رویدادهای پایان دوره و لغو اشتراک مبلغ ندارند: پایان دورهٔ پرداخت‌شده دربارهٔ پرداخت تازه چیزی نمی‌گوید و نباید مبلغ پرداخت قبلی را به آن نسبت داد.

این رویداد دربارهٔ مشترک است، نه پیامی از او. بنابراین گفت‌وگو را برای پیام خصوصی در دسترس علامت نمی‌زند، مسدود بودن کاربر را برنمی‌دارد، زمان «آخرین فعالیت» و شمارندهٔ پیام‌ها را تغییر نمی‌دهد. پرداخت با کارت به معنای نوشتن پیام نیست. اگر پلتفرم هنوز این مشترک را نمی‌شناسد، او را ایجاد می‌کند تا بتوان برچسب و مجوز به او داد.

نمونهٔ «باشگاه اشتراکی»:

  1. برای VK Donut: subscription created و VK Donut: subscription prolonged واکنش بسازید: با تغییر برچسب‌ها، برچسب «باشگاه» را با مدت ttl_days برابر 31 اضافه کنید. سپس پیوند جامعهٔ بسته را بفرستید و از فرد بخواهید درخواست عضویت بدهد.
  2. پذیرش عضویت یک گام جداست، پس از آنکه فرد درخواست را فرستاد. اقدام تغییر دسترسی‌ها → پذیرش درخواست تنها درخواستِ از پیش ثبت‌شده را با groups.approveRequest می‌پذیرد. این اقدام را در واکنشی پس از گام اول قرار دهید، مثلاً دکمهٔ «درخواست را فرستادم» یا رویداد تمدید بعدی.
  3. برای Label expired (label_expired)، اقدام تغییر دسترسی‌ها → اخراج را اجرا کنید. به این ترتیب فرد هنگام پایان اعتبار برچسب از باشگاه خارج می‌شود، حتی اگر رویداد «دوره تمام شد» از VK نرسد. ماشه‌ها را ببینید.
  4. برای VK Donut: subscription cancelled و VK Donut: subscription expired، برچسب «باشگاه» را با تغییر برچسب‌ها حذف کنید و در صورت نیاز همان لحظه فرد را اخراج کنید.

در اقدام‌های مدیریت اعضای VK، کادر چت (chat_id) باید ID جامعهٔ متصل باشد، همان عددی که کنار کانال VK دیده می‌شود. VK فقط اعضای همین جامعه را مدیریت می‌کند. ID دیگر پیش از ارسال به VK رد می‌شود. برای جامعهٔ دیگر، آن را به‌عنوان کانال جداگانه وصل کنید.

برای فعال کردن رویدادها:

  • Long Poll: بات هنگام اتصال کانال و هر بار راه‌اندازی پلتفرم، خودش مشترک رویدادها می‌شود. برای جامعه‌هایی که از قبل وصل‌اند، کار دیگری لازم نیست.
  • Callback API: در تنظیمات جامعه، Работа с API → Callback API → Типы событий → VK Donut را باز کنید و هر چهار رویداد جدول را فعال کنید.

چگونه کانال وصل کنیم

کانال‌ها را از پروژه‌ها اضافه کنید:

  1. پروژه‌ها را باز کنید و پروژه را پیدا کنید.
  2. در کارت پروژه افزودن کانال را بزنید.
  3. Telegram، WhatsApp یا VK را انتخاب کنید.
  4. اطلاعات کانال را وارد کنید: توکن برای Telegram، اطلاعات Meta برای WhatsApp یا اطلاعات جامعه برای VK.
  5. بررسی را بزنید تا GetMyBot اطلاعات را نزد پیام‌رسان بررسی کند.
  6. اتصال را بزنید.

پس از اتصال WhatsApp یا VK، نشانی وب‌هوک کانال (نماد 🔗) ظاهر می‌شود. آن را در پلتفرم مربوط ثبت کنید، یعنی در برنامهٔ Meta برای WhatsApp یا تنظیمات جامعه برای VK، تا رویدادهای ورودی به بات برسند. راهنمای WhatsApp: تنظیم وب‌هوک.

مراحل بعدی

اطلاعات اتصال کانال

برای Telegram، توکن کامل BotFather را وارد کنید. VK به توکن جامعه و ID عددی جامعه نیاز دارد؛ برای Callback API، رشتهٔ محرمانه و کد تأیید نیز لازم است. برای WhatsApp باید Phone Number ID، ID حساب تجاری WhatsApp، توکن دسترسی به حساب، Verify Token وب‌هوک و App Secret برنامهٔ Meta را وارد کنید.

اطلاعات را پیش از اتصال بررسی کنید. اگر کلیدی را عوض کردید، تنظیم مربوط را نزد ارائه‌دهنده نیز به‌روز کنید: Verify Token برای تأیید نشانی وب‌هوک و App Secret برای بررسی امضای رویداد ورودی است. هیچ‌کدام جای توکن دسترسی API را نمی‌گیرند.

رویدادهای ورودی و نشانی وب‌هوک

برای VK Callback API، نشانی نشان‌داده‌شده در MyBot را در تنظیمات سرور جامعه ثبت کنید و رشتهٔ محرمانه و کد تأیید یکسانی وارد کنید. Long Poll به نشانی عمومی یا این دو مقدار نیاز ندارد. برای WhatsApp، نشانی را در برنامهٔ Meta ثبت کنید، همان Verify Token را وارد کنید و در رویدادهای پیام لازم مشترک شوید. داشتن اطلاعات لازم برای فرستادن پیام، به‌تنهایی دریافت پیام‌های ورودی را فعال نمی‌کند.

مجوزدهی Instagram و Messenger

راهنمای اتصال، صفحهٔ مجوزدهی Meta را باز می‌کند. با حسابی وارد شوید که صفحهٔ Facebook یا حساب حرفه‌ای Instagram موردنظر را اداره می‌کند. مجوزهای خواسته‌شده را بدهید و حساب‌های این پروژه را انتخاب کنید. راهنما مجوزها، اشتراک وب‌هوک و آمادگی تحویل پیام را بررسی می‌کند؛ پیش از استفاده از کانال، خطاهای بررسی را برطرف کنید. در اتصال موجود نیز می‌توانید حساب‌های انتخاب‌شده را بازبینی کنید.