Telegram опубликовал схему OpenAPI для Bot API

Telegram выложил описание Bot API в формате OpenAPI: один файл api.json перечисляет все методы, объекты, ответы и ошибки, а также запросы, которые Telegram сам отправляет боту на вебхук. Это касается разработчиков ботов и авторов библиотек. Клиент на любом языке теперь можно сгенерировать из официального файла, а не из разобранной HTML-страницы документации. Файл лежит на corefork.telegram.org, где выложена обновлённая версия документации, и описывает текущую версию Bot API 10.3.

Что это за файл

OpenAPI (раньше назывался Swagger) — стандартный формат, в котором HTTP-интерфейс описан как данные: адреса, параметры, типы полей, коды ответов. По такому описанию генераторы строят клиентские библиотеки, валидаторы проверяют запросы, а редакторы рисуют интерактивную документацию.

Файл весит 1,83 МБ, в шапке стоят "openapi": "3.2.0" и "version": "10.3". Ревизия 3.2.0 — самая свежая у стандарта, её опубликовали 19 сентября 2025 года. Из её нововведений схема использует поле $self с собственным адресом, именованные серверы и отдельный раздел mediaTypes для повторяющихся тел ответов.

Что внутри, по подсчёту прямо по файлу:

Параметров нет у восьми методов из 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 типов. Генератор по такому описанию строит настоящий тип-сумму, а не объект со всеми полями сразу.

Файлы. 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. Telegram присылает обновление и может подписать запрос заголовком X-Telegram-Bot-Api-Secret-Token или базовой авторизацией из URL; оба способа объявлены схемами безопасности. Ответом на вебхук бот может сразу вызвать метод, и в схеме это объединение всех допустимых методов с полем method. Методы, имя которых начинается с get, а также setWebhook, deleteWebhook, close и logOut вызвать так нельзя.

23 связи (links) описывают, куда передаётся результат одной операции. file_id анимации из сообщения можно передать в sendAnimation, а file_path из getFile разрезать по косой черте на две части адреса downloadFile. Для разрезания Telegram завёл собственное расширение x-split-parameters — единственное нестандартное поле во всём файле.

Что учесть, если генерировать клиент

На обновлённой странице corefork появились три раздела, которых на основном домене пока нет. Все три касаются расхождений между схемой и поведением сервера.

64-битные идентификаторы — строки. Идентификаторы кастомных эмодзи, подарков, callback-запросов и инлайн-запросов 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 октября по этому адресу открывается страница «Page not found», как и по адресу errors.json на основном домене. Основная 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: дискриминаторы объединений, обязательность полей, лимиты длины и коды ошибок теперь заданы в схеме, а не выводятся из текста.