دریافت پیام‌ها با روش Long Polling (getUpdates)

روش Long Polling ساده‌ترین راهکار برای دریافت پیام‌ها و رویدادهای ربات بدون نیاز به داشتن دامنه عمومی یا گواهی SSL است. این روش برای توسعه، دیباگ و سرورهای محلی بسیار ایده‌آل است.

---

نحوه کار متد getUpdates

هنگامی که متد getUpdates را صدا می‌زنید، سرور تا زمانی که پیام جدیدی برسد (یا مهلت timeout به پایان برسد) اتصال را باز نگه می‌دارد.

GET POST https://botapi.codemeet.chat/bot<TOKEN>/getUpdates

پارامترهای ورودی

پارامتر	نوع داده	وضعیت	پیش‌فرض	توضیحات
offset	Integer	اختیاری	null	شناسه اولین آپدیتی که باید بازگردانده شود. برای تأیید دریافت آپدیت‌ها، مقدار update_id + 1 آخرین آپدیت را ارسال کنید.
limit	Integer	اختیاری	100	تعداد مجاز پیام‌ها در هر درخواست (بین ۱ تا ۱۰۰).
timeout	Integer	اختیاری	0	مدت زمان انتظار بر حسب ثانیه برای دریافت پیام جدید (حداکثر ۵۰ ثانیه).
allowed_updates	Array of String	اختیاری	تمام انواع	لیست انواع آپدیت‌های مجاز (مانند ["message", "callback_query"]).

---

ساختار پاسخ getUpdates

خروجی این متد آرایه‌ای از اشیاء Update است:

{
  "ok": true,
  "result": [
    {
      "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": "سلام ربات!"
      }
    },
    {
      "update_id": 1043,
      "callback_query": {
        "id": "a90f12d83b4c",
        "from": {
          "id": "c1f72b9a-1122-3344-5566-778899aabbcc",
          "is_bot": false,
          "first_name": "سارا"
        },
        "message": { "message_id": 24, "chat": { "id": "..." } },
        "data": "btn_confirm"
      }
    }
  ]
}

---

الگوریتم مدیریت offset (تأیید دریافت)

برای اینکه پیام‌های تکراری دریافت نکنید، باید پس از پردازش هر آپدیت، شناسه offset را به مقدار update_id + 1 تنظیم کنید:

sequenceDiagram
    participant Bot as ربات شما
    participant Server as سرور کدمیت

    Bot->>Server: GET /getUpdates (offset=null, timeout=30)
    Server-->>Bot: updates: [update_id: 100, update_id: 101]
    Note over Bot: پردازش پیام‌های 100 و 101
    Bot->>Server: GET /getUpdates (offset=102, timeout=30)
    Note over Server: پیام‌های زیر 102 به عنوان تحویل‌شده علامت می‌خورند
    Server-->>Bot: updates: [update_id: 102]

/// tip | نکته مهم در مورد وب‌هوک اگر قبلاً برای ربات خود وب‌هوک تنظیم کرده‌اید، قبل از استفاده از getUpdates باید وب‌هوک را با متد deleteWebhook یا دستور /deletewebhook در BotFather حذف کنید. ///