# Bale official API capability matrix — reviewed 2026-10-09

مبنای مستندات:
- https://docs.bale.ai/
- https://docs.bale.ai/miniapp
- https://docs.bale.ai/safir
- https://business.bale.ai/

**طبقه‌بندی**: «مستند رسمی» لزوماً به معنی «در این نسخه پیاده‌سازی‌شده یا تست‌شده» نیست.

| قابلیت | وضعیت در API بله | وضعیت در Bale Studio v0.1 |
|---|---|---|
| ساخت ربات با BotFather | مستند رسمی؛ بیرون از API داشبورد | اتصال ربات موجود |
| getMe | مستند رسمی | پیاده‌سازی شده، تست زنده نشده |
| setWebhook, getWebhookInfo, deleteWebhook | مستند رسمی | پیاده‌سازی شده، تست زنده نشده |
| getUpdates | مستند رسمی | استفاده نشده؛ با webhook همزمان نباشد |
| sendMessage | مستند رسمی؛ سقف 4096 کاراکتر | پیاده‌سازی شده |
| inline_keyboard / callback query | مستند رسمی؛ callback_data بین 1–64 بایت | پیاده‌سازی شده (شناسه‌های کوتاه) |
| answerCallbackQuery | مستند رسمی | پیاده‌سازی شده |
| contact/location | مستند رسمی | فقط contact برای پاسخ شماره موبایل |
| ارسال فایل/رسانه | مستند رسمی با قیود سایز/روش | هنوز پیاده نشده |
| editMessageText / deleteMessage | مستند رسمی با قیود دسترسی | هنوز پیاده نشده |
| گروه و کانال | APIهای مختلف مستند | هنوز پیاده نشده |
| پرداخت کیف پول (sendInvoice/PreCheckout/inquireTransaction) | مستند رسمی؛ نیازمند provider_token و صحت‌سنجی | هنوز پیاده نشده |
| Mini-App / initData | مستند رسمی؛ نیازمند HMAC در Backend | هنوز پیاده نشده |
| API کسب‌وکاری | مستند؛ نیازمند اعتبار/مجوز؛ متدها و نوع گیرنده محدود | هنوز پیاده نشده |
| سفیر | سرویس مستقل؛ API access key سازمان، شناسه ربات، شماره تماس 98... | هنوز پیاده نشده |
| Scheduler/Flow Builder | قابلیت داخلی خود داشبورد | Flow Builder پیاده شده؛ Scheduler نه |
| گزارش امتیاز/مدیریت کاربران | قابلیت داخلی | نسخه پایه پیاده شده |
| AI/API خارجی | وابسته به API و اعتبارنامه ثالث | پیاده نشده |

## محدودیت‌های رسمی مهم

- `https://tapi.bale.ai/bot<TOKEN>/<METHOD_NAME>` مبنای Bot API معمولی است.
- API کسب‌وکاری Base URL متفاوتی دارد: `https://tapi.bale.ai/business/bot<TOKEN>/<METHOD_NAME>`؛ مستندات فعلی تنها زیرمجموعه مشخصی از متدها را معرفی می‌کنند و `chat_id` فقط برای چت شخصی است.
- دریافت Webhook در مستندات پورت‌های `443` و `88` را ذکر می‌کند. عمر/ظرفیت صف آپدیت قبل از تحویل محدود است (مستند فعلی: 2000 آپدیت آخر تا 24 ساعت).
- برای ارسال عادی محدودیت نرخ پویا وجود دارد؛ عدد ثابت و جهانی فرض نشود. سیستم worker باید پاسخ 429 و retry_after را لحاظ کند. در نسخه اولیه الگوریتم ساده retry وجود دارد؛ کنترل نرخ تطبیقی مستقل هنوز ندارد.
- ارسال رسانه با `file_id`, URL و multipart محدودیت‌های متفاوت دارد. در Business API برای فایل‌ها فقط `file_id` آمده است.
- Mini-App باید `initData` را سرور با الگوریتم HMAC رسمی و `auth_date` بررسی کند. استفاده از initDataUnsafe بدون اعتبارسنجی قابل‌قبول نیست.
- هیچ API جدید را با استناد به شباهت تلگرام پشتیبانی قطعی فرض نکنید.