تلگرام توضیحات Bot API را در قالب OpenAPI منتشر کرد: یک فایل api.json شامل تمام متدها، اشیاء، پاسخ‌ها و خطاها، و همچنین درخواست‌هایی است که تلگرام خودش به وب‌هوک ربات ارسال می‌کند. این موضوع برای توسعه‌دهندگان ربات‌ها و نویسندگان کتابخانه‌ها اهمیت دارد. اکنون می‌توان کلاینت را در هر زبانی از فایل رسمی تولید کرد، نه از یک صفحه HTML مستندات که به صورت دستی تجزیه شده است. این فایل در corefork.telegram.org قرار دارد، جایی که نسخه به‌روز شده مستندات منتشر شده است و نسخه فعلی Bot API 10.3 را توصیف می‌کند.
این فایل چیست؟
OpenAPI (که قبلاً Swagger نامیده می‌شد) یک قالب استاندارد است که در آن رابط HTTP به صورت داده توصیف می‌شود: آدرس‌ها، پارامترها، انواع فیلدها، کدهای پاسخ. بر اساس چنین توضیحی، ژنراتورها (code generators) کتابخانه‌های کلاینت را می‌سازند، اعتبارسنج‌ها درخواست‌ها را بررسی می‌کنند، و ویرایشگرها مستندات تعاملی را ترسیم می‌کنند.
حجم فایل 1.83 مگابایت است و در هدر آن "openapi": "3.2.0" و "version": "10.3" قرار دارد. بازبینی 3.2.0 جدیدترین نسخه استاندارد است که در 19 سپتامبر 2025 منتشر شد. از جمله نوآوری‌های آن، این طرح‌واره از فیلد $self با آدرس خودش، سرورهای نام‌گذاری شده و یک بخش جداگانه mediaTypes برای بدنه‌های پاسخ تکراری استفاده می‌کند.
آنچه در داخل فایل است، بر اساس شمارش مستقیم:
| بخش | تعداد |
|---|---|
| متدهای Bot API (POST) | 185 |
| دانلود فایل (GET در سرور فایل) | 1 |
| طرح‌واره‌های اشیاء در کل | 625 |
| از این تعداد، مجموعه‌های پارامتر متدها | 177 |
ترکیب‌ها (oneOf/anyOf) | 31 |
| از این تعداد، با دیسکریمنیتور (discriminator) | 22 |
| فیلدهای با فرمت int64 | 217 |
پیوندها بین عملیات (links) | 23 |
| وب‌هوک‌ها | 1 |
هشت متد از 185 متد پارامتر ندارند، بنابراین 177 مجموعه پارامتر وجود دارد. دانلود فایل به عنوان یک عملیات جداگانه downloadFile با سرور مخصوص خود api.telegram.org/file/bot{token} توصیف شده است: در مستندات HTML، این یک پاراگراف متنی بود، نه یک متد.
آیا با مستندات مطابقت دارد؟
مجموعه متدها کاملاً مطابقت دارد. از صفحه HTML core.telegram.org/bots/api تعداد 185 نام متد استخراج می‌شود و از طرح‌واره نیز 185 عملیات، و هیچ اختلافی بین این لیست‌ها وجود ندارد.
با اشیاء پیچیده‌تر است، زیرا در حال حاضر دو نسخه از مستندات وجود دارد. در دامنه اصلی 400 شیء توصیف شده است. در corefork.telegram.org/bots/api تعداد 429 شیء وجود دارد: 30 نوع ورودی بیشتر (InputRichText و انواع آن، InputInlineKeyboardMarkup، InputLocation و غیره) و یک مورد کمتر — RichBlockThinking که در نسخه به‌روز شده از لیست تغییرات Bot API 10.3 حذف شده است. طرح‌واره با نسخه corefork مطابقت دارد: تمام 429 شیء آن در فایل موجود است.
19 طرح‌واره دیگر فقط در فایل وجود دارند. اینها ساختارهای خدماتی هستند که در متن به عنوان اشیاء جداگانه ذکر نشده‌اند: هشت پاسخ خطا (BadRequest، Unauthorized، TooManyRequests و غیره)، ترکیب‌های ChatId، ReplyMarkup، FileInput، UploadInput، و هفت نوع ورودی برای اشیاء موجود مانند InputMessageEntity و InputChatPermissions. نوع ورودی چیزی را توصیف می‌کند که ربات ارسال می‌کند، نه آنچه دریافت می‌کند: فیلدهایی که سرور خودش پر می‌کند، در آن وجود ندارند.
ترکیب‌ها و فایل‌ها چگونه توصیف شده‌اند؟
دشوارترین بخش برای کسانی که قبلاً HTML را تجزیه می‌کردند، مکان‌هایی است که یک فیلد چندین نوع را می‌پذیرد. در طرح‌واره، آنها به صورت ماشینی توصیف شده‌اند.
ترکیب‌ها با دیسکریمنیتور. ChatMember یک oneOf از شش گزینه است، و فیلد status گزینه را انتخاب می‌کند: creator به ChatMemberOwner و kicked به ChatMemberBanned منجر می‌شود. MessageOrigin، InputMedia، BotCommandScope، ReactionType و 17 نوع دیگر نیز به همین ترتیب ساختار یافته‌اند. ژنراتور بر اساس چنین توضیحی یک نوع-مجموع (sum type) واقعی می‌سازد، نه یک شیء با تمام فیلدها به صورت یکجا.
فایل‌ها. InputFile به عنوان محتوای باینری با نوع application/octet-stream توصیف شده است. فیلد عکس در sendPhoto مستقیماً به آن ارجاع نمی‌دهد، بلکه به FileInput ارجاع می‌دهد: این یا یک فایل قابل آپلود است، یا یک رشته غیرخالی — file_id یا URL. برای پیوست‌ها در آلبوم‌ها، UploadInput وجود دارد: فایل یا رشته‌ای به شکل attach://<نام>. بدنه sendPhoto به عنوان multipart/form-data اعلام شده است، و تمام فیلدهای اضافی بر پارامترهای متد مجاز هستند، اگر فایل باشند. این روشی را توصیف می‌کند که در آن فایل برای attach:// به عنوان یک بخش جداگانه از فرم می‌آید. فیلدهای تو در تو مانند caption_entities در داخل فرم به عنوان JSON علامت‌گذاری شده‌اند.
پاسخ‌ها. هر متد با یک پاکت {"ok": true, "result": …} پاسخ می‌دهد، و نوع result برای هر متد به صورت جداگانه مشخص شده است. خطاها بر اساس کدها دسته‌بندی شده‌اند: برای sendPhoto اینها 400، 401، 403، 421، 429 و 500 هستند.
::: جزئیات: چه چیزهای دیگری طرح‌واره فراتر از مستندات توصیف می‌کند؟
وب‌هوک به عنوان یک عملیات جداگانه receiveUpdate توصیف شده است. تلگرام به‌روزرسانی را ارسال می‌کند و می‌تواند درخواست را با هدر X-Telegram-Bot-Api-Secret-Token یا احراز هویت پایه از URL امضا کند؛ هر دو روش به عنوان طرح‌واره‌های امنیتی اعلام شده‌اند. در پاسخ به وب‌هوک، ربات می‌تواند بلافاصله یک متد را فراخوانی کند، و در طرح‌واره این یک ترکیب از تمام متدهای مجاز با فیلد method است. متدهایی که نامشان با get شروع می‌شود، و همچنین setWebhook، deleteWebhook، close و logOut را نمی‌توان به این روش فراخوانی کرد.
23 پیوند (links) توصیف می‌کنند که نتیجه یک عملیات به کجا منتقل می‌شود. file_id یک انیمیشن از پیام را می‌توان به sendAnimation منتقل کرد، و file_path از getFile را می‌توان با اسلش به دو بخش آدرس downloadFile تقسیم کرد. برای تقسیم، تلگرام یک افزونه اختصاصی x-split-parameters ایجاد کرده است — تنها فیلد غیر استاندارد در کل فایل.
:::
نکاتی برای تولید کلاینت
در صفحه به‌روز شده corefork سه بخش جدید ظاهر شده است که هنوز در دامنه اصلی وجود ندارند. هر سه به تفاوت‌های بین طرح‌واره و رفتار سرور مربوط می‌شوند.
شناسه‌های 64 بیتی — رشته هستند. شناسه‌های ایموجی‌های سفارشی، هدایا، درخواست‌های callback و درخواست‌های inline را Bot API به صورت رشته برمی‌گرداند، و باید آنها را نیز به صورت رشته ارسال کرد. در طرح‌واره، به عنوان مثال، CallbackQuery.id، Sticker.custom_emoji_id و Gift.id از نوع string هستند. شناسه‌های عددی کاربران و چت‌ها به صورت اعداد صحیح با فرمت int64 باقی می‌مانند، اگرچه طبق مستندات، بیت‌های معنی‌دار آنها بیش از 52 نیست.
محدودیت طول متن پس از تجزیه نشانه‌گذاری محاسبه می‌شود. maxLength متن پیام 4096 است، اما سرور کاراکترها را بدون نشانه‌گذاری HTML یا Markdown محاسبه می‌کند. اعتبارسنج طرح‌واره آنها را همانطور که هستند در رشته محاسبه می‌کند. یک متن 4100 کاراکتری با تگ‌ها توسط سرور پذیرفته می‌شود، اما یک اعتبارسنج سخت‌گیر آن را رد می‌کند، بنابراین برای فیلدهایی که با parse_mode ارسال می‌شوند، بررسی طول بر اساس طرح‌واره باید غیرفعال شود.
خطاها در یک فایل جداگانه قرار دارند. در کنار طرح‌واره، errors.json ظاهر شده است: برای هر خطا — لیستی از متدهایی که ممکن است آن را برگردانند. در فایل نسخه 10.3، لایه MTProto 227 و 945 توضیحات خطا وجود دارد: 901 مورد با کد 400، 31 مورد با کد 500، 12 مورد با کد 403 و یک مورد با 429. 343 خطای MTProto به صورت جداگانه نگاشت شده‌اند. مستندات تصریح می‌کند که متن خطاها ممکن است در هر زمان تغییر کند، بنابراین لیست برای مرجع مناسب است، اما برای مقایسه رشته‌ها در کد خیر.
نسخه 3.2 استاندارد یک سال پیش منتشر شد. بهتر است قبل از انتقال یک کتابخانه کاری به طرح‌واره، بررسی کنید که آیا یک ژنراتور خاص از mediaTypes در کامپوننت‌ها و سایر نوآوری‌های آن پشتیبانی می‌کند یا خیر.
فایل کجا و از چه زمانی قرار دارد؟
طرح‌واره فقط از corefork.telegram.org ارائه می‌شود. فیلد $self در داخل آن به core.telegram.org/bots/api.json اشاره می‌کند، اما در 13 اکتبر، این آدرس و همچنین آدرس errors.json در دامنه اصلی، صفحه «Page not found» را نشان می‌دهد. مستندات اصلی HTML هنوز به طرح‌واره اشاره‌ای نکرده است.
تاریخ انتشار در پاسخ سرور وجود ندارد: هدر Last-Modified را برنمی‌گرداند، فایل برای پنج دقیقه کش می‌شود و با هدر X-Robots-Tag: noindex از ایندکس شدن مسدود شده است. اولین کپی در آرشیو وب در 9 اکتبر 2026، ساعت 10:16 UTC تاریخ‌گذاری شده است.
در هدر طرح‌واره آمده است که هم مستندات و هم طرح‌واره توسط یک ژنراتور تولید می‌شوند که همراه با کد منبع سرور Bot API منتشر شده است. در 13 اکتبر، لینک به یک پوشه ناموجود هدایت می‌کند: در مخزن tdlib/telegram-bot-api دایرکتوری generator وجود ندارد. آخرین کامیت در آنجا در 25 آگوست تاریخ‌گذاری شده است، یک روز قبل از آن نسخه سرور به 10.3 ارتقا یافت.
قبلاً از چه چیزی استفاده می‌شد؟
Bot API قبلاً طرح‌واره ماشینی رسمی نداشت، و جامعه آن را از صفحه HTML جمع‌آوری می‌کرد. شناخته‌شده‌ترین مثال telegram-bot-api-spec است: یک اسکریپت هر روز مستندات را تجزیه می‌کند و JSON را با متدها، فیلدها و زیرنوع‌ها منتشر می‌کند. در نسخه فعلی آن Bot API 10.3، 185 متد و 400 شیء وجود دارد. پارسرهای و ژنراتورهای مشابه در tg-bot-api موجود هستند، و آرشیو طرح‌واره‌ها برای نسخه‌های قدیمی‌تر در telegram-bot-api-versions نگهداری می‌شود.
تجزیه HTML به متن نوشتاری متکی است: «Optional» در ابتدای توضیحات فیلد، کلمه «or» بین انواع، و ترتیب جداول. ویرایش چیدمان مستندات می‌تواند چنین تجزیه‌کننده‌ای را بدون حتی یک تغییر در خود API خراب کند. فایل رسمی این کار را به سمت Telegram منتقل می‌کند: دیسکریمنیتورهای (discriminators) انواع اتحادیه (union types)، اجباری بودن فیلدها، محدودیت‌های طول و کدهای خطا اکنون در طرح (schema) تعریف شده‌اند و از متن استخراج نمی‌شوند.
