Telegram Bot API uchun OpenAPI sxemasini e'lon qildi

Telegram Bot API tavsifini OpenAPI formatida e'lon qildi: bitta api.json fayli barcha metodlar, ob'ektlar, javoblar va xatolarni, shuningdek, Telegramning o'zi botga veb-xuk orqali yuboradigan so'rovlarni sanab o'tadi. Bu bot dasturchilari va kutubxona mualliflariga tegishli. Endi har qanday tildagi mijozni hujjatlarning HTML sahifasidan emas, balki rasmiy fayldan yaratish mumkin. Fayl corefork.telegram.org saytida joylashgan bo'lib, u yerda hujjatlarning yangilangan versiyasi mavjud va Bot API 10.3 ning joriy versiyasini tavsiflaydi.

Bu qanday fayl?

OpenAPI (ilgari Swagger deb nomlangan) – bu HTTP interfeysi ma'lumotlar sifatida tasvirlangan standart format: manzillar, parametrlar, maydon turlari, javob kodlari. Bunday tavsifga ko'ra, generatorlar mijoz kutubxonalarini yaratadi, validatorlar so'rovlarni tekshiradi, muharrirlar esa interaktiv hujjatlarni chizadi.

Fayl hajmi 1,83 MB bo'lib, uning sarlavhasida "openapi": "3.2.0" va "version": "10.3" ko'rsatilgan. 3.2.0 reviziyasi standartning eng so'nggi versiyasi bo'lib, u 2025-yil 19-sentyabrda e'lon qilingan. Uning yangiliklaridan sxema o'z manziliga ega $self maydonidan, nomlangan serverlardan va takrorlanuvchi javob tanalari uchun alohida mediaTypes bo'limidan foydalanadi.

Fayl ichidagi ma'lumotlar, faylning o'zidan hisoblangan holda:

185 ta metoddan sakkiztasida parametrlar yo'q, shuning uchun parametrlar to'plamlari 177 ta. Faylni yuklab olish downloadFile alohida operatsiyasi sifatida, o'zining api.telegram.org/file/bot{token} serveri bilan tasvirlangan: HTML-hujjatlarda bu metod emas, balki oddiy matnli paragraf edi.

Hujjatlarga mos keladimi?

Metodlar to'plami to'liq mos keladi. core.telegram.org/bots/api HTML sahifasidan 185 ta metod nomi, sxemadan esa 185 ta operatsiya olinadi va ro'yxatlar o'rtasida farqlar yo'q.

Ob'ektlar bilan vaziyat murakkabroq, chunki hozirda hujjatlarning ikkita versiyasi mavjud. Asosiy domenda 400 ta ob'ekt tasvirlangan. corefork.telegram.org/bots/api da esa 429 ta: 30 ta ko'proq kirish turlari (InputRichText va uning variantlari, InputInlineKeyboardMarkup, InputLocation va boshqalar) va bitta kamroq – RichBlockThinking, u yangilangan versiyada Bot API 10.3 o'zgarishlar ro'yxatidan g'oyib bo'lgan. Sxema corefork versiyasiga mos keladi: uning barcha 429 ta ob'ekti faylda mavjud.

Yana 19 ta sxema faqat faylda mavjud. Bular matnda alohida ob'ektlar sifatida mavjud bo'lmagan xizmat konstruksiyalari: sakkizta xato javobi (BadRequest, Unauthorized, TooManyRequests va boshqalar), ChatId, ReplyMarkup, FileInput, UploadInput birlashmalari va InputMessageEntity va InputChatPermissions kabi mavjud ob'ektlarning yettita kirish varianti. Kirish varianti bot yuboradigan narsani tasvirlaydi, qabul qiladigan narsani emas: serverning o'zi to'ldiradigan maydonlar unda mavjud emas.

Birlashmalar va fayllar qanday tasvirlangan?

Ilgari HTMLni tahlil qilganlar uchun eng qiyin joylar – bitta maydon bir nechta turni qabul qiladigan joylar. Sxemada ular mashina tilida tasvirlangan.

Diskriminatorli birlashmalar. ChatMember oltita variantdan iborat oneOf bo'lib, variantni status maydoni tanlaydi: creator ChatMemberOwner ga, kicked esa ChatMemberBanned ga olib boradi. MessageOrigin, InputMedia, BotCommandScope, ReactionType va yana 17 ta tur ham xuddi shunday tuzilgan. Bunday tavsifga ko'ra generator haqiqiy tur-summani yaratadi, barcha maydonlarga ega bo'lgan ob'ektni emas.

Fayllar. InputFile application/octet-stream turidagi ikkilik tarkib sifatida tasvirlangan. sendPhoto dagi fotosurat maydoni to'g'ridan-to'g'ri unga emas, balki FileInput ga ishora qiladi: bu yuklanadigan fayl yoki bo'sh bo'lmagan satr – file_id yoki URL. Albomlardagi ilovalar uchun UploadInput mavjud: fayl yoki attach://<nom> ko'rinishidagi satr. sendPhoto tanasi multipart/form-data deb e'lon qilingan va metod parametrlaridan tashqari barcha maydonlarga, agar ular fayllar bo'lsa, ruxsat beriladi. Bu attach:// uchun fayl shaklning alohida qismi sifatida keladigan usulni tasvirlaydi. Shakl ichidagi caption_entities kabi ichki maydonlar JSON sifatida belgilangan.

Javoblar. Har bir metod {"ok": true, "result": …} konverti bilan javob beradi va result turi har bir metod uchun alohida ko'rsatilgan. Xatolar kodlar bo'yicha taqsimlangan: sendPhoto uchun bular 400, 401, 403, 421, 429 va 500.

Sxema hujjatlardan tashqari yana nimani tasvirlaydi?

Veb-xuk receiveUpdate alohida operatsiyasi sifatida tasvirlangan. Telegram yangilanishni yuboradi va so'rovni X-Telegram-Bot-Api-Secret-Token sarlavhasi yoki URL dan asosiy avtorizatsiya bilan imzolashi mumkin; ikkala usul ham xavfsizlik sxemalari sifatida e'lon qilingan. Veb-xukga javoban bot darhol metodni chaqirishi mumkin va sxemada bu method maydoniga ega barcha ruxsat etilgan metodlarning birlashmasidir. Nomlari get bilan boshlanadigan metodlar, shuningdek setWebhook, deleteWebhook, close va logOut bunday chaqirilishi mumkin emas.

23 ta bog'lanish (links) bir operatsiya natijasi qayerga uzatilishini tasvirlaydi. Xabardagi animatsiyaning file_id ni sendAnimation ga uzatish mumkin, getFile dan olingan file_path ni esa downloadFile manzilining ikki qismiga bo'lish mumkin. Bo'lish uchun Telegram o'zining x-split-parameters kengaytmasini yaratgan – bu butun fayldagi yagona nostandart maydon.

Agar mijoz yaratilsa, nimani hisobga olish kerak?

Yangilangan corefork sahifasida asosiy domenda hali mavjud bo'lmagan uchta bo'lim paydo bo'ldi. Uchala bo'lim ham sxema va server xatti-harakatlari o'rtasidagi farqlarga tegishli.

64-bit identifikatorlar – satrlar. Maxsus emojilar, sovg'alar, callback-so'rovlar va inline-so'rovlarning identifikatorlarini Bot API satrlar sifatida qaytaradi va ularni ham satrlar sifatida uzatish kerak. Sxemada, masalan, CallbackQuery.id, Sticker.custom_emoji_id va Gift.id string turiga ega. Foydalanuvchilar va chatlarning raqamli identifikatorlari int64 formatidagi butun sonlar bo'lib qoladi, garchi hujjatlarga ko'ra ularda 52 dan ortiq ahamiyatli bitlar bo'lmasa ham.

Matn uzunligi limiti belgilash tahlil qilingandan keyin hisoblanadi. Xabar matnining maxLength 4096 ga teng, ammo server belgilar sonini HTML- yoki Markdown-belgilashsiz hisoblaydi. Sxema validatori ularni satr bo'yicha boricha hisoblaydi. Teglar bilan 4100 belgidan iborat matnni server qabul qiladi, ammo qat'iy validator rad etadi, shuning uchun parse_mode bilan yuboriladigan maydonlar uchun sxema bo'yicha uzunlikni tekshirishni o'chirib qo'yish kerak.

Xatolar alohida faylda joylashgan. Sxema yonida errors.json paydo bo'ldi: har bir xato uchun uni qaytarishi mumkin bo'lgan metodlar ro'yxati. Faylda 10.3 versiyasi, MTProto 227 qatlami va 945 ta xato tavsifi mavjud: 901 tasi 400 kodli, 31 tasi 500 kodli, 12 tasi 403 kodli va bittasi 429 kodli. 343 ta MTProto xatosi alohida moslashtirilgan. Hujjatlarda xato matnlari istalgan vaqtda o'zgarishi mumkinligi ta'kidlangan, shuning uchun ro'yxat ma'lumot uchun yaroqli, ammo kodda satrlarni solishtirish uchun emas.

Standartning 3.2 versiyasi bir yil oldin chiqqan. Muayyan generator komponentlardagi mediaTypes va uning boshqa yangiliklarini qo'llab-quvvatlaydimi, ishchi kutubxonani sxemaga o'tkazishdan oldin tekshirish yaxshiroqdir.

Fayl qayerda va qachondan beri mavjud?

Sxema faqat corefork.telegram.org dan taqdim etiladi. Uning ichidagi $self maydoni core.telegram.org/bots/api.json ga ishora qiladi, ammo 13-oktyabr holatiga ko'ra bu manzilda "Page not found" sahifasi ochiladi, xuddi asosiy domendagi errors.json manzilida bo'lgani kabi. Asosiy HTML-hujjatlarda sxema haqida hozircha eslatilmagan.

Server javobida nashr etilgan sana yo'q: u Last-Modified sarlavhasini bermaydi, fayl besh daqiqaga keshlanadi va X-Robots-Tag: noindex sarlavhasi bilan indeksatsiyadan yopilgan. Veb-arxivdagi birinchi nusxa 2026-yil 9-oktyabr, 10:16 UTC sanasiga tegishli.

Sxema sarlavhasida hujjatlar ham, sxema ham Bot API serverining manba kodi bilan birga nashr etilgan generator tomonidan yig'ilishi aytilgan. 13-oktyabr holatiga ko'ra, havola mavjud bo'lmagan papkaga olib boradi: tdlib/telegram-bot-api repozitoriyasida generator katalogi yo'q. U yerdagi oxirgi kommit 25-avgustga tegishli bo'lib, undan bir kun oldin server versiyasi 10.3 ga ko'tarilgan.

Bungacha nimalardan foydalanilgan?

Bot API ning rasmiy mashina o'qiydigan sxemasi ilgari mavjud emas edi va hamjamiyat uni HTML sahifasidan o'zi yig'gan. Eng mashhur misol – telegram-bot-api-spec: skript har kuni hujjatlarni tahlil qiladi va metodlar, maydonlar va kichik turlar bilan JSON faylini joylashtiradi. Uning joriy versiyasida Bot API 10.3, 185 ta metod va 400 ta ob'ekt mavjud. Shunga o'xshash parselar va generatorlar tg-bot-api da mavjud, eski versiyalar bo'yicha sxemalar arxivi esa telegram-bot-api-versions da saqlanadi.

HTML tahlili matnga asoslanadi: maydon tavsifining boshidagi "Optional" so'zi, turlar orasidagi "or" so'zlari, jadvallar tartibi. Hujjatlar formatini tahrirlash API ning o'zida hech qanday o'zgarishsiz bunday parserni buzishi mumkin. Rasmiy fayl bu ishni Telegram tomoniga o'tkazadi: birlashmalarning diskriminatorlari, maydonlarning majburiyligi, uzunlik chegaralari va xato kodlari endi sxemada belgilangan, matndan olinmaydi.