HTTP Bot API: supported methods

This document lists every Bot API method that the telesrv HTTP gateway (internal/botapi, default port 8081) actually implements, together with the parameters it accepts, the extensions it adds, and the official methods it deliberately does not support.

Russian version of this document: bot-api.ru.md.

How to use this document

• Transport
• Authentication
• Request and response conventions
• Errors
• Method summary
• Updates
• Methods: bot identity and commands
• Methods: sending
• Methods: rich messages
• Methods: ephemeral messages
• Methods: editing and deleting
• Methods: files
• Methods: webhooks
• Methods: menus, emoji status, web apps
• Methods: payments
• Markup and entities
• Limits
• Not implemented
• Demos and self-tests

Transport

<METHOD> is matched case-insensitively. Both GET and POST reach the dispatcher, so urlencoded GET requests work.

Client configuration:

• python-telegram-bot: pass --base-url http://host:8081/bot and --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" })).

Authentication

The path token must be the bot's <bot_id>:<secret> pair and its secret must match the value stored for that bot. Anything else returns HTTP 401 with ACCESS_TOKEN_INVALID. There is no separate auth header; the token in the URL is the credential, exactly like the official gateway.

File downloads (/file/bot...) are authenticated the same way.

Request and response conventions

Success:

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

Failure:

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

error_code is the HTTP status code. description is an upper-case SCREAMING_SNAKE error marker, not always the official Telegram wording — match on the marker, not on the whole string.

Field decoding is generic: JSON bodies are flattened to strings, non-string JSON values are re-marshalled to their JSON form, and multipart uses the first value of each field. This is why several methods accept both the message_text shorthand and the full InputTextMessageContent object, and why setChatMenuButton accepts both a nested menu_button object and a flat body carrying type.

Errors

Markers the gateway can return directly:

Method summary

Implemented (40 methods + 1 file route):

Updates

Only three update kinds are produced:

allowed_updates is a JSON array of up to 100 strings; unknown names parse successfully but never match anything, so do not rely on filtering to hide updates — drop the fields in the bot. The setting is accepted both by getUpdates and by setWebhook, and it persists per bot.

Ephemeral (Bot API 10.2) messages arrive as normal message updates, but their message_id belongs to the ephemeral namespace rather than the chat's message numbering, so ordinary reply_to_message_id will not address them. Replies go back through reply_parameters.ephemeral_message_id; see Methods: ephemeral messages.

Queue retention is controlled by TELESRV_BOT_API_UPDATE_RETENTION (default 24h); acknowledged updates are dropped earlier.

Methods: bot identity and commands

getMe

No parameters. Returns the bot's own User object.

setMyCommands

is_ephemeral=true marks the command as an ephemeral one: invoking it in a group produces a message only the caller can see, and the bot must answer inside the ephemeral action window. Returns true.

deleteMyCommands

Same scope rules as setMyCommands; clears the list. Returns true.

getMyCommands

Same scope rules. Returns the stored array; entries include is_ephemeral: true only when the flag is set.

Methods: sending

sendMessage

Ordinary and ephemeral addressing are mutually exclusive: with receiver_user_id set, reply_to_message_id must stay unset and reply_parameters may only carry ephemeral_message_id. Ephemeral sends accept inline keyboards only (BUTTON_TYPE_INVALID otherwise). The result is the same Message shape, with the ephemeral id in message_id.

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

All share one handler.

The file field accepts, in this order of precedence:

1. attach://<field> referencing a multipart file part;
2. an uploaded multipart part with the same field name;
3. an http:// or https:// URL (the server fetches it);
4. a file_id previously returned by getFile.

Anything else is FILE_ID_INVALID.

sendLivePhoto

Two media fields: photo (still frame) and live_photo (the video part). Both accept upload, attach://, or file_id. The video part cannot be an HTTP URL — that is FILE_ID_INVALID, matching the official restriction. Captions, parse_mode, and the ephemeral extension work as for the other media methods.

sendContact, sendLocation, sendVenue

These three are ephemeral-only: they require receiver_user_id (or a callback_query_id) and otherwise fail with EPHEMERAL_TARGET_REQUIRED.

sendContact takes chat_id, phone_number, first_name, optional last_name, and vcard (up to 2048 bytes), plus an optional inline reply_markup.

sendLocation takes chat_id, latitude (-90..90), longitude (-180..180), horizontal_accuracy (0..1500, default 0). A non-zero live_period is rejected with MEDIA_INVALID — live location is not implemented.

sendVenue adds required title and address, and accepts either foursquare_id + foursquare_type or google_place_id + google_place_type.

Methods: rich messages

sendRichMessage

Telesrv extension, Layer 228 rich text. Sends InputRichMessage instead of a plain formatted string, so tables, headings, dividers, details blocks and footers reach the client as real rich blocks.

Rules and rejections:

• exactly one of html / markdown must be non-empty; zero or both is RICH_MESSAGE_INVALID;
• blocks is parsed but rejected — RICH_MESSAGE_BLOCKS_UNSUPPORTED;
• media is parsed but rejected — RICH_MESSAGE_MEDIA_UNSUPPORTED;
• the source is capped at 256 KiB;
• business_connection_id, message_thread_id, direct_messages_topic_id, allow_paid_broadcast, and suggested_post_parameters are rejected with an explicit error instead of being silently ignored;
• rich HTML that references remote media (img, video, audio, tg-map, tg-collage, tg-slideshow) fails with WEBPAGE_MEDIA_EMPTY, because the local blob backend cannot materialize an arbitrary URL atomically. The documented workaround (see cmd/bots/bedolagaformat) is to retry once with the logo removed rather than degrade to a classic menu.

Supported HTML elements: b/strong, i/em, u/ins, s/strike/del, tg-spoiler, span (only as <span class="tg-spoiler">), a, code, pre (with class="language-…"), blockquote, tg-emoji, tg-time, footer, and table (with the bordered and striped attributes, per-cell alignment). tg-time requires unix in 1..2^31-1 and a format built from t, T, d, D, w/W, or exactly r/R for a relative timestamp.

Markdown input is parsed by the same rich builder used on the MTProto side, so #-style headings, --- dividers, pipe tables, > quotes, fenced code and footer blocks all work.

editMessageText accepts the same rich_message object, and there is no separate editMessageRichMessage method.

Methods: ephemeral messages

Ephemeral messages (Bot API 10.2) are visible only to their receiver, who sees a "only visible to you" notice. telesrv supports the whole lifecycle.

Sending is done through the ordinary methods with receiver_user_id:

• sendMessage — text;
• the media methods — media plus a caption;
• sendContact, sendLocation, sendVenue — ephemeral only.

Addressing rules:

• receiver_user_id is required and must be a positive integer;
• callback_query_id may replace it as the anchor (the receiver is derived from the query);
• reply_parameters.ephemeral_message_id replies to an existing ephemeral message, and cannot be combined with callback_query_id;
• reply_parameters.message_id is the ordinary reply form and is not combined with a receiver;
• message_thread_id is the top message of the ephemeral discussion group;
• the action window is 15 seconds — after it the server answers EPHEMERAL_ACTION_EXPIRED.

Editing and deleting:

media is an InputMedia-like object: type (one of photo, animation, audio, document, video, live_photo), the file field, and optional caption, parse_mode, caption_entities, width, height, duration, title, performer. live_photo uses photo for the still and media for the video. Raw uploads are not allowed here — only file_id, attach://-free file references, or HTTPS URLs (FILE_ID_INVALID otherwise).

reply_markup is inline-only, and its presence matters: sending reply_markup with an empty value clears the keyboard.

Methods: editing and deleting

editMessageText

The main edit method. It covers both ordinary and rich text edits, and both chat messages and inline messages.

For an inline_message_id the result is a boolean; for a chat message it is the updated Message. An edit that changes nothing returns MESSAGE_NOT_MODIFIED.

editMessageCaption

Only a photo or document message (photo, video, animation, audio, voice, file) has a caption; a text message returns MESSAGE_HAS_NO_CAPTION. Returns the updated Message. Works in private chats and in channels/supergroups.

editMessageReplyMarkup

chat_id + message_id (no inline_message_id yet) and an optional inline reply_markup. Only the keyboard changes; an omitted reply_markup removes it. Returns the updated Message.

There is no editMessageMedia, editMessageLiveLocation, or stopMessageLiveLocation — use editMessageText (or the ephemeral variants) instead.

sendChatAction

Returns true. The status is transient, like MTProto messages.setTyping: nothing is stored. business_connection_id is not supported.

deleteMessage

chat_id + message_id. Returns true. Deleting an already-deleted or foreign message returns false or an error, as with the official gateway.

answerCallbackQuery

Returns true.

Methods: files

getFile

file_id must be a telesrv-issued id. The result always has file_unique_id == file_id and file_path == file_id, so the download URL is /file/bot<TOKEN>/<file_id>. Foreign or unknown ids are FILE_ID_INVALID.

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

Streams the file, chunk by chunk, with the stored MIME type and Content-Length. The path is the file_id; a path with extra segments is 404 FILE_NOT_FOUND.

Methods: webhooks

setWebhook

certificate (and any uploaded certificate part) is rejected with CERTIFICATE_PINNING_UNSUPPORTED; use a publicly trusted certificate. ip_address is rejected with IP_ADDRESS_UNSUPPORTED — the gateway uses the configured address list.

Setting a webhook while getUpdates is long-polling returns 409 CONFLICT. While a delivery is in flight, setWebhook waits up to 20 seconds for it to finish and returns 409 CONFLICT only if the delivery is still running.

Delivery behaviour:

• one HTTP POST per update, with a single Update object as the body (not an array like getUpdates returns);
• header X-Telegram-Bot-Api-Secret-Token carries the secret token;
• Content-Type: application/json; any 2xx counts as delivered;
• redirects are never followed, so the secret cannot leak to another host;
• up to max_connections updates are delivered in parallel, 16 bots and 64 concurrent HTTP requests overall;
• failures retry with exponential backoff from 1s up to 5 minutes, plus a small per-bot jitter;
• delivery is confirmed up to the first failed update, so nothing is skipped.

getWebhookInfo

Returns url, has_custom_certificate (always false here), pending_update_count, and — when a webhook is configured — max_connections, allowed_updates, last_error_date, last_error_message.

deleteWebhook

drop_pending_updates is optional. Like setWebhook, it waits up to 20 seconds for an in-flight delivery and returns 409 only if that delivery is still running.

Methods: menus, emoji status, web apps

setChatMenuButton / getChatMenuButton

menu_button is {"type": "default"}, {"type": "commands"}, or {"type": "web_app", "text": "...", "web_app": {"url": "..."}}. A flat body that carries type at the top level is also accepted, which keeps older library serializers working. Setting returns true; getting returns the current button (never null — an unset button reads as {"type": "default"}).

setUserEmojiStatus

user_id, emoji_status_custom_emoji_id, emoji_status_expiration_date. Requires the user to have granted the bot permission to set their status (otherwise 403 USER_PERMISSION_DENIED) and to be a Premium user (PREMIUM_ACCOUNT_REQUIRED). Returns true.

answerWebAppQuery

web_app_query_id plus result. Only InlineQueryResult of type article is supported: id (up to 64 characters), title, description, url (HTTPS only), input_message_content (or the message_text shorthand), reply_markup (inline only). Other result types are RESULT_TYPE_INVALID. The response contains inline_message_id when the answer produced one.

savePreparedInlineMessage

user_id, result (same article restriction), and the peer filters allow_user_chats, allow_bot_chats, allow_group_chats, allow_channel_chats. Returns {id, expiration_date}.

Methods: payments

giftPremiumSubscription

Pays for a Premium gift out of the bot's Stars balance, through the same durable Stars pipeline as MTProto payments.sendStarsForm.

Send an Idempotency-Key HTTP header (or the local request_id field) — the allowed charset is [A-Za-z0-9] plus -, _, ., : up to 128 characters. Replaying the same key with the same request returns the stored result; replaying it with a different recipient, plan, price, or text is IDEMPOTENCY_KEY_INVALID. Requests without any key still work, but each retry charges again, so always send a key.

dropPendingUpdates

Implemented: discards the bot's unconfirmed queued updates and answers true. A bot that has fallen behind needs it, otherwise it spends forever working through a backlog while pre_checkout_query, which lives 10 seconds, quietly expires.

answerPreCheckoutQuery

Implemented. Before any Stars move, the payer waits for the bot's answer for at most 10 seconds (Telegram's requirement). The bot receives a pre_checkout_query update and answers with pre_checkout_query_id, ok and, when ok=false, an error_message.

• ok=true — the Stars are charged and the bot receives successful_payment;
• ok=false — the payment is cancelled and error_message is shown to the payer;
• no answer within 10 seconds — the payment does not go through (PAYMENT_FAILED).

The timeout never degrades into charging anyway: a silent bot means a refusal, otherwise pre-checkout would verify nothing. Only the bot that owns the order may answer; a stale pre_checkout_query_id gets QUERY_ID_INVALID. The currency and invoice_payload in the answer are not compared against what the bot recorded at sendInvoice, so that check stays on the bot side, same as in Telegram.

answerShippingQuery

Recognized, but answers HTTP 501 METHOD_NOT_FOUND: a Stars payment has no shipping step, so there is nothing to answer.

Markup and entities

reply_markup accepts exactly one constructor:

Inline keyboard buttons (exactly one action per button, otherwise BUTTON_INVALID): url, callback_data (up to 64 bytes), 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. Every button also accepts text (required), style (primary / danger / success / omitted), and icon_custom_emoji_id. Unknown fields are rejected rather than ignored.

Reply keyboard buttons: a plain string, or an object with text plus one of 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), or web_app.

Message entities (for entities / caption_entities, and for the date_time entity, which takes 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.

Limits: 256 entities per message (ENTITIES_TOO_LONG), offsets in UTF-16 code units, unknown types are ENTITY_TYPE_UNSUPPORTED.

Limits

Not implemented

Every other official method returns HTTP 404 METHOD_NOT_FOUND. The most commonly reached ones:

• editing: editMessageMedia, editMessageLiveLocation, stopMessageLiveLocation, stopPoll, and inline_message_id for editMessageCaption / editMessageReplyMarkup;
• media groups and the rest of the send* surface: sendMediaGroup, sendPoll, sendDice, sendGame;
• payments: createInvoiceLink, sendInvoice, answerPreCheckoutQuery, answerShippingQuery, getStarTransactions, refundStarPayment;
• chat administration: banChatMember, unbanChatMember, restrictChatMember, promoteChatMember, setChatPermissions, setChatPhoto, deleteChatPhoto, pinChatMessage, unpinChatMessage, unpinAllChatMessages, setChatTitle, setChatDescription, leaveChat;
• queries: getChat, getChatAdministrators, getChatMember, getChatMemberCount, getForumTopic*, getUserChatBoosts;
• messages: forwardMessage, forwardMessages, copyMessage, copyMessages, sendPoll, getFile-adjacent helpers;
• bot administration: setMyName, setMyDescription, setMyShortDescription, setMyDefaultAdministratorRights, deleteWebhook for other bots, close, logOut;
• reactions, games, and business-account methods.

MTProto clients are unaffected: everything implemented for the official Android/iOS/Desktop clients is reached over MTProto, not HTTP. See docs/premium-stars.md for the shared Stars and Premium pipelines.

Demos and self-tests