U یونیوم مستندات

Bot API

دریافت پیام

دریافت updateها با long polling یا webhook و قواعد مهم offset، timeout و allowed_updates.

دو روش دریافت

برای هر کلید API، یک مسیر دریافت را انتخاب کنید:

روش مناسب برای نکته
getUpdates تست، ابزارهای ساده، jobهای کوچک کلاینت باید offset را درست جلو ببرد
webhook production، تحویل سریع، چند سرویس endpoint شما باید پاسخ 2xx بدهد

getUpdates

curl "https://api.uniom.ir/bot<API_KEY>/getUpdates?timeout=30&limit=20"

پس از دریافت updateها، در درخواست بعدی offset را برابر بزرگ‌ترین update_id + 1 بگذارید تا پیام تکراری نگیرید.

curl "https://api.uniom.ir/bot<API_KEY>/getUpdates?offset=123457&timeout=30"

update_id، offset و idempotency

منطق consumer را این‌طور نگه دارید:

  1. پاسخ هر poll را کامل بخوانید و بزرگ‌ترین update_id را پیدا کنید.
  2. فقط بعد از پردازش موفق، offset بعدی را جلو ببرید.
  3. اگر worker شما restart شد، آخرین update_id تاییدشده را از storage بخوانید.
  4. اگر webhook استفاده می‌کنید، همان update ممکن است بعد از خطای 4xx/5xx دوباره فرستاده شود؛ handler باید idempotent باشد.

فیلتر نوع update

با allowed_updates می‌توانید فقط نوع‌هایی را بگیرید که برای برنامه لازم است:

curl -X POST "https://api.uniom.ir/bot<API_KEY>/getUpdates" \
  -H "Content-Type: application/json" \
  -d '{"allowed_updates":["message","edited_message","channel_post"],"timeout":30}'

برای فهرست کامل enumها به مفاهیم اصلی نگاه کنید. اگر بعداً این فیلتر را عوض کنید، updateهای قدیمی ممکن است برای مدت کوتاهی با تنظیم قبلی هم برسند.

ساختار update

هر update معمولاً فقط یکی از فیلدهای اصلی را دارد، مثل message یا edited_message.

{
  "update_id": 123456,
  "message": {
    "message_id": 55,
    "chat": {"id": 991, "type": "private"},
    "text": "سلام"
  }
}

الگوی پیشنهادی پردازش

یک worker پایدار برای polling معمولاً این شکل را دارد:

  1. getUpdates را با timeout مثبت صدا بزنید.
  2. response را لاگ سبک یا trace-friendly ذخیره کنید.
  3. هر update را بر اساس نوع اصلی (message, callback_query, ...) route کنید.
  4. نتیجه پردازش را ثبت کنید.
  5. offset را فقط بر اساس بزرگ‌ترین update موفق جلو ببرید.

جلوگیری از چند poll هم‌زمان

برای یک token فقط یک worker را مسئول getUpdates کنید. چند poller هم‌زمان می‌توانند باعث تکرار، رقابت offset یا خطای conflict شوند.

بخش‌های مرتبط