نشرت تيليجرام وصف واجهة برمجة تطبيقات البوت (Bot API) بصيغة OpenAPI: حيث يسرد ملف واحد api.json جميع الأساليب والكائنات والاستجابات والأخطاء، بالإضافة إلى الطلبات التي ترسلها تيليجرام نفسها إلى البوت عبر الويب هوك (webhook). يُعد هذا الأمر ذا أهمية لمطوري البوتات ومؤلفي المكتبات. يمكن الآن إنشاء عميل بأي لغة برمجة من الملف الرسمي، بدلاً من الاعتماد على صفحة وثائق HTML التي تم تحليلها. يوجد الملف على corefork.telegram.org، حيث تتوفر النسخة المحدثة من الوثائق، ويصف الإصدار الحالي من Bot API 10.3.
ما هو هذا الملف؟
OpenAPI (التي كانت تُعرف سابقًا باسم Swagger) هي صيغة قياسية تُوصف فيها واجهة HTTP كبيانات: العناوين، المعاملات (parameters)، أنواع الحقول، ورموز الاستجابة. بناءً على هذا الوصف، تقوم المولدات (generators) بإنشاء مكتبات العملاء، وتتحقق المدققات (validators) من الطلبات، وتصمم المحررات وثائق تفاعلية.
يبلغ حجم الملف 1.83 ميجابايت، ويحتوي في ترويسة (header) على "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 |
| الويب هوكس (Webhooks) | 1 |
لا تحتوي ثمانية أساليب من أصل 185 على معاملات، لذا فإن عدد مجموعات المعاملات هو 177. يتم وصف تنزيل الملف كعملية منفصلة downloadFile مع خادمها الخاص api.telegram.org/file/bot{token}: في وثائق HTML، كان هذا مجرد فقرة نثرية وليست أسلوبًا.
هل يتطابق مع الوثائق؟
تتطابق مجموعة الأساليب بالكامل. يتم استخراج 185 اسم أسلوب من صفحة HTML core.telegram.org/bots/api، و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 سابقًا هو الأماكن التي يقبل فيها حقل واحد عدة أنواع. في المخطط، يتم وصفها آليًا.
الاتحادات مع مميز (discriminator). ChatMember هو oneOf من ستة خيارات، ويختار الحقل status الخيار: creator يؤدي إلى ChatMemberOwner، وkicked يؤدي إلى ChatMemberBanned. بنفس الطريقة يتم تنظيم MessageOrigin، InputMedia، BotCommandScope، ReactionType و17 نوعًا آخر. يقوم المولد (generator) بناءً على هذا الوصف بإنشاء نوع مجموع حقيقي (sum type)، وليس كائنًا يحتوي على جميع الحقول مرة واحدة.
الملفات. يتم وصف InputFile كمحتوى ثنائي من نوع application/octet-stream. لا يشير حقل الصورة في sendPhoto إليه مباشرة، بل إلى FileInput: وهو إما ملف يتم تحميله، أو سلسلة نصية غير فارغة — file_id أو URL. بالنسبة للمرفقات في الألبومات، يوجد UploadInput: ملف أو سلسلة نصية على شكل attach://<اسم>. يتم الإعلان عن جسم sendPhoto كـ multipart/form-data، ويُسمح بجميع الحقول الإضافية على معاملات الأسلوب إذا كانت ملفات. يصف هذا الأسلوب عندما يأتي الملف لـ attach:// كجزء منفصل من النموذج. يتم وضع علامة JSON على الحقول المتداخلة مثل caption_entities داخل النموذج.
الاستجابات. يستجيب كل أسلوب بمغلف {"ok": true, "result": …}، ويتم تحديد نوع result لكل أسلوب على حدة. يتم تقسيم الأخطاء حسب الرموز: بالنسبة لـ sendPhoto، تكون 400، 401، 403، 421، 429 و500.
ماذا يصف المخطط أيضًا بالإضافة إلى الوثائق
يتم وصف الويب هوك (webhook) كعملية منفصلة 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 بت — سلاسل نصية. تُرجع Bot API معرفات الرموز التعبيرية المخصصة، والهدايا، وطلبات رد الاتصال (callback queries)، وطلبات السطر الواحد (inline queries) كسلاسل نصية، ويجب تمريرها أيضًا كسلاسل نصية. في المخطط، على سبيل المثال، 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 من المعيار قبل عام. من الأفضل التحقق مما إذا كان المولد (generator) المحدد يدعم mediaTypes في المكونات وبقية ابتكاراته قبل نقل مكتبة عاملة إلى المخطط.
أين يوجد الملف ومنذ متى؟
يتم توفير المخطط فقط من corefork.telegram.org. يشير حقل $self بداخله إلى core.telegram.org/bots/api.json، ولكن في 13 أكتوبر، تفتح صفحة "Page not found" على هذا العنوان، وكذلك على عنوان errors.json على النطاق الرئيسي. لا تذكر وثائق HTML الرئيسية المخطط حتى الآن.
لا يوجد تاريخ نشر في استجابة الخادم: لا يعطي رأس Last-Modified، ويتم تخزين الملف مؤقتًا لمدة خمس دقائق ومحمي من الفهرسة بواسطة رأس X-Robots-Tag: noindex. أول نسخة في أرشيف الويب مؤرخة في 9 أكتوبر 2026، الساعة 10:16 بالتوقيت العالمي المنسق.
يذكر رأس المخطط أن الوثائق والمخطط يتم تجميعهما بواسطة مولد (generator) تم نشره مع الكود المصدري لخادم Bot API. في 13 أكتوبر، يشير الرابط إلى مجلد غير موجود: في مستودع tdlib/telegram-bot-api لا يوجد دليل generator. آخر التزام (commit) هناك مؤرخ في 25 أغسطس، وقبل يوم واحد منه ارتفع إصدار الخادم إلى 10.3.
ما الذي كان يستخدم قبل ذلك؟
لم يكن لدى Bot API مخطط رسمي قابل للقراءة آليًا من قبل، وكان المجتمع يجمعه بنفسه من صفحة HTML. المثال الأكثر شهرة هو telegram-bot-api-spec: يقوم السكريبت بتحليل الوثائق يوميًا وينشر JSON مع الأساليب والحقول والأنواع الفرعية. في إصداره الحالي، Bot API 10.3، 185 أسلوبًا و400 كائن. توجد محللات ومولدات مماثلة في tg-bot-api، ويتم تخزين أرشيف المخططات للإصدارات القديمة في telegram-bot-api-versions.
تيليجرام ينشر مخطط OpenAPI لـ Bot API
يعتمد تحليل HTML على الصياغة النصية: مثل كلمة «Optional» في بداية وصف الحقل، وكلمة «or» بين الأنواع، وترتيب الجداول. يمكن أن يؤدي تعديل تنسيق الوثائق إلى تعطيل محلل كهذا دون أي تغيير واحد في الـ API نفسه. ينقل الملف الرسمي هذه المهمة إلى جانب تيليجرام: فأصبحت مُميِّزات أنواع الاتحاد، وإلزامية الحقول، وحدود الطول، وأكواد الأخطاء محددة الآن في المخطط، بدلًا من استنتاجها من النص.
