HTTP Bot API: поддерживаемые методы

Документ перечисляет все методы Bot API, которые HTTP-шлюз telesrv (internal/botapi, порт по умолчанию 8081) действительно реализует, вместе с принимаемыми параметрами, добавленными расширениями и официальными методами, которые сознательно не поддержаны.

Английская версия этого документа: bot-api.en.md.

Как пользоваться этим документом

• Транспорт
• Аутентификация
• Формат запросов и ответов
• Ошибки
• Сводка методов
• Обновления
• Методы: бот и команды
• Методы: отправка
• Методы: rich-сообщения
• Методы: ephemeral-сообщения
• Методы: редактирование и удаление
• Методы: файлы
• Методы: webhooks
• Методы: меню, emoji status и web apps
• Методы: платежи
• Разметка и entities
• Лимиты
• Не реализовано
• Демо и self-тесты

Транспорт

<METHOD> сопоставляется без учёта регистра. Диспетчер доступен и по GET, и по POST, поэтому urlencoded-запросы методом GET работают.

Настройка клиентов:

• python-telegram-bot: --base-url http://host:8081/bot и --base-file-url http://host:8081/file/bot;
• aiogram: TelegramAPIServer.from_base("http://host:8081");
• grammY: new Api("host:8081") либо api.config.use((ctx) => ({ apiRoot: "http://host:8081/bot" })).

Аутентификация

Токен в пути должен быть парой <bot_id>:<secret> бота, а секрет — совпадать со значением, сохранённым для этого бота. Всё остальное даёт HTTP 401 с ACCESS_TOKEN_INVALID. Отдельного auth-заголовка нет: токен в URL и есть credential, ровно как на официальном шлюзе.

Скачивание файлов (/file/bot...) аутентифицируется так же.

Формат запросов и ответов

Успех:

{"ok": true, "result": {}}

Ошибка:

{"ok": false, "error_code": 400, "description": "CHAT_ID_INVALID"}

error_code — это HTTP-статус. description — маркер ошибки в верхнем регистре (SCREAMING_SNAKE), не обязательно в официальных формулировках Telegram — сопоставляйте по маркеру, а не по всей строке.

Разбор полей универсальный: JSON-тело «расплющивается» в строки, нестроковые значения перемаршируются в свой JSON, а в multipart берётся первое значение каждого поля. Поэтому часть методов принимает и сокращение message_text, и полный объект InputTextMessageContent, а setChatMenuButton — и вложенный объект menu_button, и «плоское» тело с type на верхнем уровне.

Ошибки

Маркеры, которые шлюз может вернуть напрямую:

Сводка методов

Реализовано (40 методов + 1 файловый маршрут):

Обновления

Шлюз порождает только три вида обновлений:

allowed_updates — JSON-массив из не более 100 строк; неизвестные имена разбираются без ошибки, но не совпадают ни с чем, поэтому не рассчитывайте на фильтрацию как на способ спрятать обновления — отбрасывайте лишние поля в боте. Настройка принимается и getUpdates, и setWebhook и хранится отдельно для каждого бота.

Ephemeral-сообщения (Bot API 10.2) приходят как обычные message-обновления, но их message_id принадлежит ephemeral-пространству, а не нумерации сообщений чата, поэтому обычный reply_to_message_id их не адресует. Ответ идёт через reply_parameters.ephemeral_message_id; см. Методы: ephemeral-сообщения.

Время жизни очереди задаёт TELESRV_BOT_API_UPDATE_RETENTION (по умолчанию 24h); подтверждённые обновления удаляются раньше.

Методы: бот и команды

getMe

Без параметров. Возвращает собственный объект User бота.

setMyCommands

is_ephemeral=true помечает команду как ephemeral: её вызов в группе создаёт сообщение, видимое только вызвавшему, и бот должен ответить в пределах ephemeral-окна. Возвращает true.

deleteMyCommands

Те же правила по scope, что и у setMyCommands; очищает список. Возвращает true.

getMyCommands

Те же правила по scope. Возвращает сохранённый массив; поле is_ephemeral: true присутствует только у помеченных команд.

Методы: отправка

sendMessage

Обычная и ephemeral-адресация взаимоисключающи: если задан receiver_user_id, поле reply_to_message_id должно остаться пустым, а reply_parameters может нести только ephemeral_message_id. Для ephemeral-отправки допустимы лишь inline-клавиатуры (иначе BUTTON_TYPE_INVALID). Результат — та же структура Message, где message_id содержит ephemeral-id.

sendPhoto, sendAnimation, sendAudio, sendDocument, sendSticker, sendVideo, sendVideoNote, sendVoice

У них один общий обработчик.

Файловое поле принимает, по убыванию приоритета:

1. attach://<field>, ссылающееся на multipart-часть;
2. загруженную multipart-часть с тем же именем поля;
3. URL http:// или https:// (сервер забирает его сам);
4. file_id, ранее выданный getFile.

Всё остальное — FILE_ID_INVALID.

sendLivePhoto

Два медиа-поля: photo (кадр) и live_photo (видеочасть). Оба принимают загрузку, attach:// или file_id. Видеочасть не может быть HTTP-URL — это FILE_ID_INVALID, как и в официальном ограничении. Подписи, parse_mode и ephemeral-расширение работают так же, как в остальных медиа-методах.

sendContact, sendLocation, sendVenue

Эти три метода только ephemeral: они требуют receiver_user_id (или callback_query_id), иначе EPHEMERAL_TARGET_REQUIRED.

sendContact принимает chat_id, phone_number, first_name, необязательные last_name и vcard (до 2048 байт), плюс необязательную inline-разметку.

sendLocation принимает chat_id, latitude (-90..90), longitude (-180..180), horizontal_accuracy (0..1500, по умолчанию 0). Ненулевой live_period отклоняется с MEDIA_INVALID — live-локация не реализована.

sendVenue добавляет обязательные title и address и принимает либо foursquare_id + foursquare_type, либо google_place_id + google_place_type.

Методы: rich-сообщения

sendRichMessage

Расширение telesrv, rich-текст Layer 228. Отправляет InputRichMessage вместо обычной отформатированной строки, поэтому таблицы, заголовки, разделители, блоки details и footer доходят до клиента настоящими rich-блоками.

Правила и отказы:

• ровно одно из html / markdown должно быть непустым; ноль или оба — RICH_MESSAGE_INVALID;
• blocks разбирается, но отклоняется — RICH_MESSAGE_BLOCKS_UNSUPPORTED;
• media разбирается, но отклоняется — RICH_MESSAGE_MEDIA_UNSUPPORTED;
• исходник ограничен 256 KiB;
• business_connection_id, message_thread_id, direct_messages_topic_id, allow_paid_broadcast и suggested_post_parameters отклоняются явной ошибкой, а не игнорируются молча;
• rich HTML со ссылкой на удалённое медиа (img, video, audio, tg-map, tg-collage, tg-slideshow) падает с WEBPAGE_MEDIA_EMPTY, потому что локальный blob-backend не может атомарно материализовать произвольный URL. Описанный в cmd/bots/bedolagaformat обходной путь — повторить запрос один раз без логотипа, не деградируя до classic-меню.

Поддерживаемые HTML-элементы: b/strong, i/em, u/ins, s/strike/del, tg-spoiler, span (только как <span class="tg-spoiler">), a, code, pre (с class="language-…"), blockquote, tg-emoji, tg-time, footer и table (с атрибутами bordered и striped, выравниванием по ячейкам). Для tg-time обязателен unix в диапазоне 1..2^31-1 и format, собранный из t, T, d, D, w/W либо ровно r/R для относительной отметки времени.

Markdown разбирает тот же rich-builder, что и на стороне MTProto, поэтому работают заголовки #, разделители ---, pipe-таблицы, цитаты >, огороженный код и footer-блоки.

editMessageText принимает тот же объект rich_message; отдельного метода editMessageRichMessage нет.

Методы: ephemeral-сообщения

Ephemeral-сообщения (Bot API 10.2) видны только получателю, который видит пометку «видно только вам». telesrv поддерживает весь жизненный цикл.

Отправка идёт через обычные методы с receiver_user_id:

• sendMessage — текст;
• медиа-методы — медиа плюс подпись;
• sendContact, sendLocation, sendVenue — только ephemeral.

Правила адресации:

• receiver_user_id обязателен и должен быть положительным целым;
• вместо него якорем может быть callback_query_id (получатель берётся из query);
• reply_parameters.ephemeral_message_id отвечает на существующее ephemeral-сообщение и не комбинируется с callback_query_id;
• reply_parameters.message_id — обычная форма ответа, с получателем не комбинируется;
• message_thread_id — верхнее сообщение ephemeral-треда;
• окно действия — 15 секунд, после него сервер отвечает EPHEMERAL_ACTION_EXPIRED.

Правка и удаление:

media — объект в духе InputMedia: type (одно из photo, animation, audio, document, video, live_photo), файловое поле и необязательные caption, parse_mode, caption_entities, width, height, duration, title, performer. Для live_photo кадр берётся из photo, видео — из media. Сырая загрузка здесь не допускается — только file_id, ссылка на файл без attach:// или HTTPS-URL (иначе FILE_ID_INVALID).

reply_markup принимается только inline, и важно его наличие: переданный пустой reply_markup снимает клавиатуру.

Методы: редактирование и удаление

editMessageText

Основной метод правки. Покрывает и обычный текст, и rich-текст, и сообщения чата, и inline-сообщения.

Для inline_message_id результат — булево значение, для сообщения чата — обновлённый Message. Правка, ничего не меняющая, даёт MESSAGE_NOT_MODIFIED.

editMessageCaption

Подпись есть только у сообщения с фото или документом (фото, видео, анимация, аудио, голосовое, файл); для текстового сообщения возвращается MESSAGE_HAS_NO_CAPTION. Возвращает обновлённый Message. Работает в личных чатах и в каналах/супергруппах.

editMessageReplyMarkup

chat_id + message_id (без inline_message_id) и необязательный inline reply_markup. Меняется только клавиатура; отсутствие reply_markup её убирает. Возвращает обновлённый Message.

Методов editMessageMedia, editMessageLiveLocation и stopMessageLiveLocation нет — используйте editMessageText (или ephemeral-варианты).

sendChatAction

Возвращает true. Статус временный, как MTProto messages.setTyping: ничего не сохраняется. business_connection_id не поддерживается.

deleteMessage

chat_id + message_id. Возвращает true. Удаление уже удалённого или чужого сообщения возвращает false либо ошибку, как и на официальном шлюзе.

answerCallbackQuery

Возвращает true.

Методы: файлы

getFile

file_id должен быть выдан telesrv. В результате всегда file_unique_id == file_id и file_path == file_id, поэтому URL скачивания — /file/bot<TOKEN>/<file_id>. Чужие или неизвестные id — FILE_ID_INVALID.

GET /file/bot<TOKEN>/<file_path>

Отдаёт файл потоком, чанк за чанком, с сохранённым MIME-типом и Content-Length. Путь — это file_id; путь с лишними сегментами даёт 404 FILE_NOT_FOUND.

Методы: webhooks

setWebhook

certificate (и любая загруженная часть сертификата) отклоняется с CERTIFICATE_PINNING_UNSUPPORTED — нужен публично доверенный сертификат. ip_address отклоняется с IP_ADDRESS_UNSUPPORTED: шлюз использует сконфигурированный список адресов.

Установка webhook во время long-polling getUpdates возвращает 409 CONFLICT. Во время доставки setWebhook ждёт её завершения до 20 секунд и возвращает 409 CONFLICT, только если доставка всё ещё идёт.

Поведение доставки:

• один HTTP POST на обновление, тело — объект Update, а не массив, как у getUpdates;
• заголовок X-Telegram-Bot-Api-Secret-Token несёт секретный токен;
• Content-Type: application/json; успехом считается любой 2xx;
• редиректы не следуются, поэтому секрет не утечёт на другой хост;
• параллельно доставляется до max_connections обновлений, суммарно 16 ботов и 64 одновременных HTTP-запроса;
• при сбое повтор экспоненциально от 1s до 5 минут плюс небольшой бот-зависимый джиттер;
• доставка подтверждается до первого неуспешного обновления, так что ничего не пропускается.

getWebhookInfo

Возвращает url, has_custom_certificate (здесь всегда false), pending_update_count и — если webhook настроен — max_connections, allowed_updates, last_error_date, last_error_message.

deleteWebhook

drop_pending_updates необязателен. Как и setWebhook, ждёт завершения текущей доставки до 20 секунд и возвращает 409, только если она всё ещё идёт.

Методы: меню, emoji status и web apps

setChatMenuButton / getChatMenuButton

menu_button — это {"type": "default"}, {"type": "commands"} или {"type": "web_app", "text": "...", "web_app": {"url": "..."}}. Также принимается «плоское» тело с type на верхнем уровне — это держит работоспособность старых сериализаторов библиотек. Установка возвращает true, чтение — текущую кнопку (никогда не null: незаданная кнопка читается как {"type": "default"}).

setUserEmojiStatus

user_id, emoji_status_custom_emoji_id, emoji_status_expiration_date. Требуется, чтобы пользователь разрешил боту менять свой статус (иначе 403 USER_PERMISSION_DENIED) и чтобы он был Premium (PREMIUM_ACCOUNT_REQUIRED). Возвращает true.

answerWebAppQuery

web_app_query_id плюс result. Поддерживается только InlineQueryResult типа article: id (до 64 символов), title, description, url (только HTTPS), input_message_content (или сокращение message_text), reply_markup (только inline). Другие типы результатов — RESULT_TYPE_INVALID. В ответе есть inline_message_id, если ответ его породил.

savePreparedInlineMessage

user_id, result (то же ограничение на article) и фильтры пиров allow_user_chats, allow_bot_chats, allow_group_chats, allow_channel_chats. Возвращает {id, expiration_date}.

Методы: платежи

giftPremiumSubscription

Оплачивает подарок Premium из Stars-баланса бота через тот же надёжный Stars-пайплайн, что и MTProto payments.sendStarsForm.

Передавайте HTTP-заголовок Idempotency-Key (или локальное поле request_id) — допустимый charset [A-Za-z0-9] плюс -, _, ., :, до 128 символов. Повтор того же ключа с тем же запросом возвращает сохранённый результат; повтор с другим получателем, тарифом, ценой или текстом — IDEMPOTENCY_KEY_INVALID. Запросы без ключа тоже работают, но каждый ретрай списывает средства снова, поэтому ключ всегда стоит слать.

dropPendingUpdates

Работает: отбрасывает неподтверждённые апдейты в очереди бота и отвечает true. Нужен боту, который отстал, — иначе он годами продирается через бэклог, а pre_checkout_query живёт всего 10 секунд и протухает незамеченным.

answerPreCheckoutQuery

Работает. Перед списанием Stars плательщик ждёт ответа бота не более 10 секунд (требование Telegram). Бот получает апдейт pre_checkout_query и отвечает pre_checkout_query_id плюс ok и, при ok=false, error_message.

• ok=true — Stars списываются, боту приходит successful_payment;
• ok=false — оплата отменяется, error_message показывается плательщику;
• нет ответа за 10 секунд — оплата считается несостоявшейся (PAYMENT_FAILED).

Таймаут не переходит в «списать напрямую»: не ответивший бот означает отказ, иначе pre-checkout ничего бы не проверял. Ответ принимается только от бота, которому принадлежит заказ; на устаревший pre_checkout_query_id бот получает QUERY_ID_INVALID. Сумма и invoice_payload в запросе не сверяются с тем, что бот записывал при sendInvoice, — проверка остаётся на стороне бота, как и в Telegram.

answerShippingQuery

Метод распознаётся, но отвечает HTTP 501 METHOD_NOT_FOUND: оплата Stars не имеет шага доставки, отвечать не на что.

Разметка и entities

reply_markup принимает ровно один конструктор:

Кнопки inline-клавиатуры (ровно одно действие на кнопку, иначе BUTTON_INVALID): url, callback_data (до 64 байт), web_app, login_url (url, bot_username, forward_text, request_write_access), switch_inline_query, switch_inline_query_current_chat, switch_inline_query_chosen_chat, copy_text. У каждой кнопки также есть text (обязателен), style (primary / danger / success / пусто) и icon_custom_emoji_id. Неизвестные поля отклоняются, а не игнорируются.

Кнопки reply-клавиатуры: обычная строка либо объект с text и одним из request_contact, request_location, request_poll (type), request_users (request_id, user_is_bot, user_is_premium, max_quantity, request_name, request_username, request_photo), request_chat (request_id, chat_is_channel, chat_is_forum, chat_has_username, chat_is_created, user_administrator_rights, bot_administrator_rights, bot_is_member, request_title, request_username, request_photo) или web_app.

Message entities (для entities / caption_entities, а также entity date_time, которая принимает unix_time + date_time_format):

bold, italic, underline, strikethrough, code, pre (language), text_link (url), text_mention (user.id), spoiler, blockquote, expandable_blockquote, custom_emoji (custom_emoji_id), mention, hashtag, cashtag, bot_command, url, email, phone_number, bank_card_number, date_time.

Лимиты: 256 entity на сообщение (ENTITIES_TOO_LONG), смещения в кодовых единицах UTF-16, неизвестные типы — ENTITY_TYPE_UNSUPPORTED.

Лимиты

Не реализовано

Все остальные официальные методы возвращают HTTP 404 METHOD_NOT_FOUND. Чаще всего до них доходят:

• правка: editMessageMedia, editMessageLiveLocation, stopMessageLiveLocation, stopPoll, а также inline_message_id для editMessageCaption / editMessageReplyMarkup;
• медиагруппы и остальной send*-набор: sendMediaGroup, sendPoll, sendDice, sendGame;
• платежи: createInvoiceLink, sendInvoice, answerPreCheckoutQuery, answerShippingQuery, getStarTransactions, refundStarPayment;
• администрирование чатов: banChatMember, unbanChatMember, restrictChatMember, promoteChatMember, setChatPermissions, setChatPhoto, deleteChatPhoto, pinChatMessage, unpinChatMessage, unpinAllChatMessages, setChatTitle, setChatDescription, leaveChat;
• запросы: getChat, getChatAdministrators, getChatMember, getChatMemberCount, getForumTopic*, getUserChatBoosts;
• сообщения: forwardMessage, forwardMessages, copyMessage, copyMessages, sendPoll и смежные с getFile помощники;
• администрирование бота: setMyName, setMyDescription, setMyShortDescription, setMyDefaultAdministratorRights, close, logOut;
• реакции, игры и методы business-аккаунтов.

MTProto-клиенты это не затрагивает: всё, что реализовано для официальных клиентов Android/iOS/Desktop, доступно по MTProto, а не по HTTP. Общие Stars- и Premium-пайплайны описаны в docs/premium-stars.md.

Демо и self-тесты