Bot API

رفتار Bot API

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

مسیر و token

در کدهای تلگرامی معمولاً آدرس این شکل را دارد:

https://api.telegram.org/bot<TOKEN>/METHOD_NAME

در یونیوم فقط base URL و token عوض می‌شود:

https://api.uniom.ir/bot<API_KEY>/METHOD_NAME

مقدار <API_KEY> همان کلیدی است که در پنل یونیوم برای یک credential می‌سازید. scopeهای کلید تعیین می‌کنند ارسال، دریافت یا عملیات مدیریتی مجاز است یا نه.

شکل درخواست

برای متدهای Bot API، این روش‌ها را در کلاینت خود پشتیبانی کنید:

نوع ارسال پارامتر	کاربرد
query string	درخواست‌های ساده مثل `getMe` یا تست سریع
`application/json`	انتخاب پیشنهادی برای بیشتر متدهای ارسال و مدیریت پیام
`application/x-www-form-urlencoded`	سازگاری با SDKها و فرم‌های قدیمی‌تر
`multipart/form-data`	upload فایل، عکس، ویدئو، سند و voice

برای فایل‌ها، از multipart استفاده کنید و timeout کلاینت را متناسب با اندازه فایل تنظیم کنید.

شکل پاسخ

پاسخ موفق با ok=true و فیلد result برمی‌گردد:

{
  "ok": true,
  "result": {}
}

در خطاها، ok=false است و معمولاً error_code و description دارید. بعضی خطاها ممکن است فیلد parameters هم داشته باشند؛ اگر SDK شما از retry خودکار، rate limit یا migration استفاده می‌کند، این فیلد را حذف نکنید.

{
  "ok": false,
  "error_code": 400,
  "description": "Bad Request: chat not found"
}

دریافت update

برای هر API key فقط یکی از این دو مسیر را فعال نگه دارید:

روش	رفتار مورد انتظار
`getUpdates`	long polling؛ بعد از پردازش، `offset` را به `update_id + 1` جلو ببرید.
webhook	یونیوم update را با POST به endpoint شما می‌فرستد؛ پاسخ 2xx یعنی تحویل موفق.

هر update معمولاً یک نوع اصلی دارد، مثل message، edited_message یا channel_post. اگر allowed_updates را تغییر دادید، ممکن است updateهای قبلی برای مدت کوتاهی با فیلتر قبلی برسند؛ کد دریافت را idempotent بنویسید.

تفاوت‌های مهم در یونیوم

یونیوم یک لایه منطبق بر APIهای تلگرام برای چند پیام‌رسان می‌دهد، اما قابلیت نهایی به پلتفرم و credential بستگی دارد. برای production این فرض‌ها را نگه دارید:

هر متد جدید تلگرام فقط وقتی در یونیوم قابل اتکاست که در /openapi.json وجود داشته باشد.
فیلدهای ناشناخته در update را نادیده نگیرید؛ آن‌ها را در مدل داخلی حفظ کنید یا لاگ بگیرید تا تغییرات جدید باعث crash نشود.
برای قابلیت‌های اختصاصی تلگرام مثل business، Stars، gifts، suggested posts و Mini Apps، قبل از rollout روی همان credential هدف تست بگیرید.
اگر webhook شما می‌خواهد هم‌زمان پاسخ Bot API بدهد، مسیر قابل اتکاتر این است که ابتدا 2xx برگردانید و درخواست Bot API را جداگانه از worker خود ارسال کنید.

اگر از یک bot یا workflow موجود مهاجرت می‌کنید، صفحه مهاجرت از تلگرام به یونیوم را کنار این نکته‌ها نگه دارید.