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.
| Item | Value |
|---|---|
| Method endpoint | http(s)://<host>/bot<TOKEN>/<METHOD> |
| File download | http(s)://<host>/file/bot<TOKEN>/<file_path> |
| Listener setting | TELESRV_BOT_API_ADDR; an empty value disables the gateway |
| Public address shown by BotFather | TELESRV_BOT_API_PUBLIC_URL; empty shows none |
| Request body limit | 25 MiB upload + 1 MiB overhead (FILE_TOO_BIG) |
| Accepted content types | application/json, multipart/form-data, application/x-www-form-urlencoded |
<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").new Api("host:8081") / `api.config.use((ctx) => ({ apiRoot:"http://host:8081/bot" }))`.
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.
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.
Markers the gateway can return directly:
| Marker | HTTP | Notes |
|---|---|---|
ACCESS_TOKEN_INVALID | 401 | bad or unknown token |
METHOD_NOT_FOUND | 404 / 501 | unknown method, or the feature is not wired in this deployment |
BAD_REQUEST | 400 | unclassified failure |
CHAT_ID_INVALID | 400 | chat_id missing, zero, or unparsable |
MESSAGE_ID_INVALID | 400 | message_id missing or <= 0 |
MESSAGE_IDENTIFIER_INVALID | 400 | inline_message_id mixed with chat_id/message_id |
MESSAGE_EMPTY | 400 | no text given |
MESSAGE_TOO_LONG | 400 | over the text limit |
MESSAGE_NOT_MODIFIED | 400 | edit that changes nothing |
REPLY_PARAMETERS_INVALID | 400 | conflicting reply selectors |
REPLY_MESSAGE_ID_INVALID | 400 | negative or malformed reply target |
MESSAGE_THREAD_ID_INVALID | 400 | ephemeral top-message id out of range |
ENTITY_INVALID, ENTITY_BOUNDS_INVALID, ENTITY_TYPE_UNSUPPORTED, ENTITIES_TOO_LONG | 400 | entity list problems |
FILE_ID_INVALID, FILE_TOO_BIG, MEDIA_INVALID | 400 | file/media problems |
BUTTON_INVALID, BUTTON_TYPE_INVALID, BUTTON_DATA_INVALID, BUTTON_URL_INVALID | 400 | markup problems |
RICH_MESSAGE_INVALID, RICH_MESSAGE_TOO_LONG, RICH_MESSAGE_DATE_INVALID, RICH_MESSAGE_BLOCKS_UNSUPPORTED, RICH_MESSAGE_MEDIA_UNSUPPORTED, RICH_MESSAGE_OPTION_UNSUPPORTED | 400 | rich message problems |
WEBPAGE_MEDIA_EMPTY | 400 | rich HTML referenced remote media the local blob backend cannot materialize |
EFFECT_ID_INVALID, VALUE_INVALID | 400 | bad numeric parameter |
BOT_COMMAND_INVALID | 400 | malformed or oversized commands |
BOT_COMMAND_SCOPE_UNSUPPORTED | 400 | non-default scope, or any language_code |
EPHEMERAL_MESSAGE_ID_INVALID, EPHEMERAL_TARGET_REQUIRED, EPHEMERAL_ACTION_EXPIRED | 400 | ephemeral addressing problems |
QUERY_ID_INVALID, USER_ID_INVALID, RESULT_ID_INVALID, RESULT_ID_EMPTY, RESULT_TYPE_INVALID | 400 | query/user/result problems |
OFFSET_INVALID | 400 | getUpdates offset below -10000 |
ALLOWED_UPDATES_INVALID | 400 | not a JSON array of up to 100 strings |
ALLOWED_UPDATES_UNSUPPORTED | 501 | gateway without the update-control service |
MAX_CONNECTIONS_INVALID | 400 | outside 1..100 |
SECRET_TOKEN_INVALID | 400 | characters outside [A-Za-z0-9_-], or longer than 256 |
WEBHOOK_URL_INVALID | 400 | not an absolute http(s) URL, longer than 2048, has userinfo/fragment, or a port outside 1..65535 |
CERTIFICATE_PINNING_UNSUPPORTED | 400 | certificate / uploaded certificate supplied |
IP_ADDRESS_UNSUPPORTED | 400 | ip_address supplied |
WEBHOOK_UNSUPPORTED | 501 | gateway without the webhook service |
METHOD_NOT_FOUND | 501 | answerShippingQuery |
BLOCKED_USER_EMOJI_STATUS_SERVICE_MISSING, BLOCKED_WEBAPP_QUERY_SERVICE_MISSING, BLOCKED_PREPARED_INLINE_SERVICE_MISSING | 501 | optional service not wired |
USER_PERMISSION_DENIED | 403 | emoji status without the required user grant |
PREMIUM_ACCOUNT_REQUIRED | 400 | emoji status without Premium |
PREMIUM_GIFT_SELF_INVALID, PREMIUM_GIFT_CODE_INVALID, BALANCE_TOO_LOW, STAR_COUNT_INVALID, MONTH_COUNT_INVALID | 400 | premium gift problems |
IDEMPOTENCY_KEY_INVALID | 400 | conflicting request_id/Idempotency-Key, or bad charset/length |
PAYMENT_FORM_INVALID | 400 | payment form rejected |
CHAT_WRITE_FORBIDDEN, CHAT_ADMIN_REQUIRED | 400 | rights missing |
USER_BOT_REQUIRED | 400 | target is not a bot user |
CONFLICT: ... | 409 | concurrent poll or webhook delivery |
INTERNAL_SERVER_ERROR | 500 / 503 | store or transport failure |
Implemented (40 methods + 1 file route):
| Group | Methods |
|---|---|
| Bot & commands | getMe, setMyCommands, deleteMyCommands, getMyCommands |
| Updates | getUpdates |
| Text | sendMessage, sendRichMessage |
| Media | sendPhoto, sendAnimation, sendAudio, sendDocument, sendLivePhoto, sendSticker, sendVideo, sendVideoNote, sendVoice |
| Location | sendContact, sendLocation, sendVenue |
| Edit/delete | editMessageText, editMessageCaption, editMessageReplyMarkup, deleteMessage |
| Chat actions | sendChatAction |
| Ephemeral edit/delete | editEphemeralMessageText, editEphemeralMessageMedia, editEphemeralMessageCaption, editEphemeralMessageReplyMarkup, deleteEphemeralMessage |
| Callback | answerCallbackQuery |
| Files | getFile, GET /file/bot<TOKEN>/<file_path> |
| Webhooks | setWebhook, deleteWebhook, getWebhookInfo |
| Menus & status | setChatMenuButton, getChatMenuButton, setUserEmojiStatus |
| Web apps & inline | answerWebAppQuery, savePreparedInlineMessage |
| Payments | giftPremiumSubscription |
| Blocked by design | answerShippingQuery (HTTP 501) |
Only three update kinds are produced:
allowed_updates value | Update key |
|---|---|
message | message |
edited_message | edited_message |
callback_query | callback_query |
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.
getMeNo parameters. Returns the bot's own User object.
setMyCommands| Parameter | Type | Notes |
|---|---|---|
commands | JSON array | up to 100 entries of {command, description, is_ephemeral} |
scope | object | only {"type":"default"} is accepted |
language_code | string | must be empty |
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.
deleteMyCommandsSame scope rules as setMyCommands; clears the list. Returns true.
getMyCommandsSame scope rules. Returns the stored array; entries include is_ephemeral: true only when the flag is set.
sendMessage| Parameter | Type | Notes |
|---|---|---|
chat_id | integer | required, non-zero; negative for groups/channels |
text | string | required, up to 4096 characters after formatting |
parse_mode | string | HTML, Markdown, MarkdownV2, or omitted for plain text |
entities | JSON array | used when parse_mode is absent; ignored otherwise |
reply_markup | object | any of the four constructors, see Markup |
disable_web_page_preview | boolean | |
disable_notification | boolean | |
reply_to_message_id | integer | |
receiver_user_id | integer | telesrv extension: switches the call to an ephemeral send |
callback_query_id | integer | ephemeral send anchored to a callback query |
reply_parameters | object | {ephemeral_message_id} for ephemeral replies, {message_id} for ordinary ones |
message_thread_id | integer | ephemeral: the top message id of the discussion group |
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, sendVoiceAll share one handler.
| Parameter | Type | Notes |
|---|---|---|
chat_id | integer | required |
<kind> | string / file | the method's own field: photo, animation, audio, document, sticker, video, video_note, voice |
caption | string | up to 1024 characters |
parse_mode, caption_entities | as in sendMessage | |
reply_markup | object | all four constructors |
disable_notification, reply_to_message_id | ||
width, height, duration, title, performer | integer / string | accepted and forwarded as metadata hints |
emoji | string | sticker only |
receiver_user_id, callback_query_id, reply_parameters, message_thread_id | same ephemeral extension as sendMessage |
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.
sendLivePhotoTwo 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, sendVenueThese 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.
sendRichMessageTelesrv 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.
| Parameter | Type | Notes |
|---|---|---|
chat_id | integer | required |
rich_message | object | {"html": "..."} or {"markdown": "..."}, plus optional is_rtl and skip_entity_detection |
reply_markup | object | inline keyboards only |
reply_parameters | object | {"message_id": N}; the legacy reply_to_message_id is also accepted, but not both |
disable_notification, protect_content | boolean | |
message_effect_id | integer | message effect id |
Rules and rejections:
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;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;
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.
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;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 derivedfrom 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 notcombined with a receiver;
message_thread_id is the top message of the ephemeral discussion group; EPHEMERAL_ACTION_EXPIRED.
Editing and deleting:
| Method | Parameters |
|---|---|
editEphemeralMessageText | chat_id, receiver_user_id, ephemeral_message_id, text, parse_mode, entities, reply_markup |
editEphemeralMessageCaption | same, with caption + caption_entities |
editEphemeralMessageMedia | same, plus media (see below) |
editEphemeralMessageReplyMarkup | same, plus reply_markup only |
deleteEphemeralMessage | chat_id, receiver_user_id, ephemeral_message_id |
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.
editMessageTextThe main edit method. It covers both ordinary and rich text edits, and both chat messages and inline messages.
| Parameter | Type | Notes |
|---|---|---|
chat_id + message_id | one addressing mode | |
inline_message_id | string | the other mode; must not be mixed with the first |
text | string | one content form |
rich_message | object | the other content form; must not be mixed with text |
parse_mode, entities | as in sendMessage | |
reply_markup | object | inline only; presence clears when empty |
disable_web_page_preview | boolean |
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| Parameter | Type | Notes |
|---|---|---|
chat_id + message_id | required; inline_message_id is not supported yet (INLINE_MESSAGE_ID_UNSUPPORTED) | |
caption | string | up to 1024 characters; omitted or empty removes the caption |
parse_mode, caption_entities | as in sendPhoto | |
reply_markup | object | inline only; omitted keeps the keyboard, empty clears it |
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.
editMessageReplyMarkupchat_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| Parameter | Type | Notes |
|---|---|---|
chat_id | integer | a private chat, or a channel/supergroup where the bot is a member |
action | string | typing, upload_photo, record_video, upload_video, record_voice, upload_voice, upload_document, choose_sticker, find_location, record_video_note, upload_video_note |
message_thread_id | integer | forum topic, optional |
Returns true. The status is transient, like MTProto messages.setTyping: nothing is stored. business_connection_id is not supported.
deleteMessagechat_id + message_id. Returns true. Deleting an already-deleted or foreign message returns false or an error, as with the official gateway.
answerCallbackQuery| Parameter | Type | Notes |
|---|---|---|
callback_query_id | string | required |
text | string | notification text |
url | string | |
show_alert | boolean | modal instead of toast |
cache_time | integer | seconds |
Returns true.
getFilefile_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.
setWebhook| Parameter | Type | Notes |
|---|---|---|
url | string | empty value deletes the webhook instead |
secret_token | string | [A-Za-z0-9_-], up to 256 characters |
max_connections | integer | 1..100, default 40 |
allowed_updates | JSON array | see Updates |
drop_pending_updates | boolean |
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 DNS address list. Before each connection, every resolved IP must be public; loopback, private, link-local and reserved addresses are blocked. Connections use the validated numeric IP, and HTTP proxy environment variables are ignored. For trusted self-hosted bots that need internal destinations, explicitly set TELESRV_BOT_API_WEBHOOK_ALLOW_PRIVATE_NETWORKS=true. This grants every bot access to the server's internal network; leave it disabled on multi-user servers. Blocked delivery is reported through getWebhookInfo and retried normally.
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:
POST per update, with a single Update object as the body (not an array like getUpdates returns);
X-Telegram-Bot-Api-Secret-Token carries the secret token;Content-Type: application/json; any 2xx counts as delivered;max_connections updates are delivered in parallel, 16 bots and 64concurrent HTTP requests overall;
small per-bot jitter;
getWebhookInfoReturns 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.
deleteWebhookdrop_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.
setChatMenuButton / getChatMenuButtonmenu_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"}).
setUserEmojiStatususer_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.
answerWebAppQueryweb_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.
savePreparedInlineMessageuser_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}.
giftPremiumSubscriptionPays for a Premium gift out of the bot's Stars balance, through the same durable Stars pipeline as MTProto payments.sendStarsForm.
| Parameter | Type | Notes |
|---|---|---|
user_id | integer | recipient; self-gifts are rejected |
month_count | integer | 1..120 |
star_count | integer | positive, at most 10^15 |
text | string | up to 128 characters |
text_parse_mode, text_entities | restricted entity set | |
request_id | string | telesrv extension for idempotency |
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.
dropPendingUpdatesImplemented: 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.
answerPreCheckoutQueryImplemented. 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;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.
answerShippingQueryRecognized, but answers HTTP 501 METHOD_NOT_FOUND: a Stars payment has no shipping step, so there is nothing to answer.
reply_markup accepts exactly one constructor:
| Constructor | Notes |
|---|---|
inline_keyboard | rows of buttons |
keyboard | reply keyboard; resize_keyboard, one_time_keyboard, is_persistent, input_field_placeholder, selective |
remove_keyboard | remove_keyboard: true, selective |
force_reply | force_reply: true, input_field_placeholder, selective |
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.
| Limit | Value |
|---|---|
| Text length | 4096 characters after parsing |
| Caption length | 1024 characters |
| Entities per message | 256 |
| Inline result id | 64 bytes |
| Callback data | 64 bytes |
Commands per setMyCommands | 100 |
| Upload size | 25 MiB per file |
allowed_updates entries | 100 |
getUpdates limit | default and maximum 100 |
getUpdates timeout | clamped to 0..50 seconds |
max_connections | 1..100, default 40 |
| Rich message source | 256 KiB |
getFile offset/limit | offset ignored; size reported in full |
Every other official method returns HTTP 404 METHOD_NOT_FOUND. The most commonly reached ones:
editMessageMedia, editMessageLiveLocation, stopMessageLiveLocation, stopPoll, and inline_message_id for editMessageCaption / editMessageReplyMarkup;
send* surface: 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-adjacent helpers;
setMyName, setMyDescription, setMyShortDescription, setMyDefaultAdministratorRights, deleteWebhook for other bots, close, logOut;
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.
| Path | Purpose |
|---|---|
cmd/bots/ptbecho | python-telegram-bot echo against the gateway, including an ephemeral command demo |
cmd/bots/aiogramecho | aiogram 3 echo, ephemeral replies, reply and inline keyboards |
cmd/bots/bedolagaformat | HTML / Markdown / MarkdownV2, rich menus via sendRichMessage, Telegram Login |
cmd/bots/botcheck | Go probe: imports the bot token over MTProto and checks the bot loop |
cmd/bots/botdemo | Go example: a bot sending to a channel or user on a timer |
cmd/bots/grammystore | Production grammY bot on the HTTP gateway (Postgres, own deployment) |
scripts/botapi_echo_once.py | Single-shot send/receive self-test |
scripts/botapi_receive_selftest.py | Update-queue and webhook self-test |