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

مبانی

مفاهیم اصلی

واژه‌ها و الگوهایی که قبل از کار با API یونیوم باید روشن باشند.

APIهای منطبق بر APIهای تلگرام

مسیرهای Bot API در یونیوم این الگو را دارند:

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

متدها با GET و POST کار می‌کنند، و برای پارامترها می‌توانید از query string، فرم، JSON یا multipart استفاده کنید. برای فایل‌ها از multipart استفاده کنید.

توکن در یونیوم

در تلگرام، token معمولاً token بات است. در یونیوم، token همان API key است. این کلید به یک credential یا حساب متصل‌شده اشاره می‌کند و scopeهای آن مشخص می‌کند چه کاری مجاز است.

credential

credential یعنی حساب متصل‌شده به یونیوم. یک کاربر می‌تواند چند credential داشته باشد، مثلاً یک حساب ایتا و یک حساب بله. کلید API معمولاً به یک credential وصل می‌شود.

chat_id

بسته به پلتفرم و متد، chat_id در یونیوم فقط یک شناسه عددی ساده نیست و می‌تواند چند شکل داشته باشد:

شکل نمونه کاربرد
username @example ارسال به کاربر یا کانال قابل resolve
شناسه عددی 123456789 استفاده از شناسه‌ای که از API گرفته‌اید
شماره تلفن +989123456789 وقتی پلتفرم و حساب اجازه resolve با شماره را بدهند
شناسه صریح کاربر #1559499 وقتی user id دقیق را از تعامل قبلی می‌دانید

قاعده عملی برای انتخاب فرمت:

  1. اگر username دارید، @username معمولاً ساده‌ترین و پایدارترین انتخاب است.
  2. اگر از update ورودی آمده‌اید، همان chat_id عددی برگشتی را نگه دارید.
  3. اگر فقط شماره موبایل را دارید، از قالب E.164 مثل +989123456789 استفاده کنید.
  4. اگر می‌خواهید کاربر را صریح و نه chat یا کانال هدف بگیرید، از قالب #user_id استفاده کنید.

برای کد production بهتر است بعد از resolve اولیه، شناسه برگشتی از API را ذخیره کنید و در loopهای بعدی دوباره به resolve با شماره یا username وابسته نباشید.

قالب پاسخ

پاسخ‌های Bot API این قالب را نگه می‌دارند:

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

در خطاها معمولاً ok=false، error_code و description می‌گیرید.

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

polling و webhook با هم فعال نیستند

مثل Telegram Bot API، دریافت پیام با getUpdates و webhook دو مسیر جایگزین هستند. وقتی webhook فعال باشد، long polling برای همان credential نباید هم‌زمان استفاده شود.

update_id و ترتیب پردازش

هر update یک update_id دارد. برای کدی که قرار است شبیه Telegram Bot API رفتار کند، این قواعد را نگه دارید:

  1. همیشه بزرگ‌ترین update_id دیده‌شده را ذخیره کنید.
  2. در polling، درخواست بعدی را با offset = last_update_id + 1 بفرستید.
  3. در webhook، handler را idempotent بنویسید تا اگر retry شد، update تکراری دوباره اثر نگذارد.
  4. فقط به زمان ارسال تکیه نکنید؛ ترتیب اصلی برای consumer همان update_id است.

enumهای اصلی update

در هر update حداکثر یکی از فیلدهای اصلی زیر باید وجود داشته باشد. برای allowed_updates هم همین نام‌ها را می‌فرستید.

نوع update معنی زمان رایج استفاده
message پیام جدید کاربر، گروه یا کانال بات‌های متنی و جریان اصلی inbox
edited_message نسخه ویرایش‌شده یک پیام بات‌هایی که ویرایش را track می‌کنند
channel_post پست جدید کانال ربات‌های کانالی
edited_channel_post ویرایش پست کانال مانیتورینگ کانال
business_connection اتصال یا قطع اتصال حساب business سناریوهای Telegram Business
business_message پیام جدید از حساب business پشتیبانی یا CRM
edited_business_message ویرایش پیام business همگام‌سازی inbox
deleted_business_messages حذف پیام‌های business audit و sync
message_reaction تغییر reaction کاربر روی پیام engagement یا moderation
message_reaction_count تغییر شمارش reactionهای ناشناس آمار و analytics
inline_query جستجوی inline بات‌های inline
chosen_inline_result انتخاب نتیجه inline توسط کاربر tracking و feedback
callback_query کلیک روی دکمه inline فرم‌ها، منوها، تایید عملیات
shipping_query پرسش هزینه/روش ارسال فروش و invoice
pre_checkout_query تایید نهایی قبل از پرداخت checkout
purchased_paid_media خرید محتوای paid media فروش محتوا
poll تغییر وضعیت poll نظرسنجی‌هایی که خود بات ساخته
poll_answer تغییر رای کاربر در poll workflowهای رای‌گیری
my_chat_member تغییر وضعیت خود بات در یک chat block/unblock یا promote/demote بات
chat_member تغییر وضعیت یک عضو chat moderation و کنترل دسترسی
chat_join_request درخواست عضویت در chat کانال‌ها و گروه‌های تاییدمحور
chat_boost افزوده‌شدن یا تغییر boost قابلیت‌های مدیریتی کانال/گروه
removed_chat_boost حذف boost از chat گزارش تغییرات boost
managed_bot ایجاد یا تغییر managed bot جریان‌های جدید Bot API 9.6

برای بیشتر پروژه‌ها، لیست اولیه allowed_updates معمولاً از message، edited_message، callback_query، my_chat_member و در صورت نیاز chat_member شروع می‌شود.

if you come from Telegram docs