معرفی

کدمیت مجموعه‌ای از APIهای استاندارد وب‌سرویس بات (Bot API) را در اختیار توسعه‌دهندگان قرار می‌دهد که با استفاده از آن‌ها می‌توان انواع ربات‌های هوشمند، دستیارهای خدماتی و سامانه‌های تعاملی را ایجاد و مدیریت کرد. برای استفاده از این APIها، مراحل زیر را دنبال کنید.

مراحل استفاده

1. با استفاده از BotFather به آدرس @BotFather در کدمیت، یک بات ایجاد کنید.

2. توکن دریافتی را ذخیره کرده و در مراحل بعدی برای احراز هویت درخواست‌ها از آن استفاده کنید.

3. با استفاده از توکن مرحله‌ی قبل و متد مورد نظر، یک URL با قالب زیر ایجاد کرده و درخواست خود را با متد POST (یا GET) ارسال کنید.

https://botapi.codemeet.chat/bot{token}/{method}

توضیحات روش‌های دریافت رویدادها

پس از ساخت بات در BotFather، برای اینکه بات شما از اقدامات کاربران (ارسال پیام، کلیک روی دکمه‌ها و …) مطلع شود، دو روش استاندارد وجود دارد:

روش ۱: فراخوانی متد getUpdates (Long Polling)

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

برای پیاده‌سازی، باید در یک حلقه با ارسال پارامتر offset (شناسه آخرین آپدیت پردازش‌شده + ۱)، متد getUpdates را صدا بزنید.

این روش برای محیط‌های محلی و توسعه بسیار ساده، سریع و بدون نیاز به سرور عمومی است.

---

روش ۲: دریافت اطلاعات از طریق وب‌هوک setWebhook (Webhook)

در این روش، با تنظیم آدرس سرور خود از طریق متد setWebhook، به‌محض وقوع هر رویداد مرتبط با بات (مانند ارسال پیام یا کلیک روی دکمه)، سرور کدمیت یک درخواست POST حاوی شیء Update را به آدرس وب‌هوک شما ارسال می‌کند.

/// note | نیازمندی‌های وب‌هوک - این روش نیازمند یک سرور با دامنه عمومی و پشتیبانی از SSL (HTTPS) است، زیرا پلتفرم تنها به آدرس‌های امن متصل می‌شود. - در صورت بروز خطا در سرور شما، تلاش‌های مجدد بر اساس سیستم صف و Outbox انجام می‌گیرد. ///

---

ساختار رویدادهای دریافتی (Update)

در هر دو روش (Polling و Webhook)، رویدادها در قالب شیء Update تحویل داده می‌شوند که مهم‌ترین انواع آن عبارتند از:

۱. دریافت پیام جدید (message)

هر زمان کاربر پیامی متنی، تصویر، دستور /start یا فایلی به ربات ارسال کند، شیء message دریافت می‌شود:

نمونه بدنه JSON :

{
  "update_id": 1042,
  "message": {
    "message_id": 25,
    "date": 1724419200,
    "chat": {
      "id": "e9b2a1c0-4411-4fa3-9f88-d4508671b122",
      "type": "private"
    },
    "from": {
      "id": "c1f72b9a-1122-3344-5566-778899aabbcc",
      "is_bot": false,
      "first_name": "سارا",
      "username": "sara_dev"
    },
    "text": "سلام ربات"
  }
}

۲. دریافت کلیک دکمه‌های شیشه‌ای (callback_query)

هرگاه کاربر روی یکی از دکمه‌های شیشه‌ای زیر پیام‌ها (InlineKeyboardButton) کلیک کند، شیء callback_query ارسال می‌شود:

نمونه بدنه JSON :

{
  "update_id": 1043,
  "callback_query": {
    "id": "a90f12d83b4c",
    "from": {
      "id": "c1f72b9a-1122-3344-5566-778899aabbcc",
      "is_bot": false,
      "first_name": "سارا",
      "username": "sara_dev"
    },
    "message": {
      "message_id": 24,
      "chat": {
        "id": "e9b2a1c0-4411-4fa3-9f88-d4508671b122",
        "type": "private"
      },
      "text": "لطفاً یکی از گزینه‌های زیر را انتخاب کنید:"
    },
    "data": "menu_settings"
  }
}

---

انتخاب روش مناسب دریافت رویدادها

• روش getUpdates (Long Polling): مناسب برای شروع سریع، محیط‌های لوکال و پروژه‌هایی که فاقد دامنه عمومی یا سرور مجهز به گواهی SSL هستند.
• روش setWebhook (Webhook): مناسب برای پروژه‌های عملیاتی (Production)، پرسرعت و پایدار در مقیاس بالا.

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