A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Telegram API is how an app or AI agent works through a Telegram bot: sending messages to a chat, receiving incoming updates, sending photos and documents, and managing members of a group. Access is granted through a single bot token, which has no scopes and carries every action the bot is capable of, so what a bot can actually do is bounded by the chats it belongs to and the administrator rights it holds there. Telegram can also push activity to the bot as it happens, rather than the bot asking again and again.
How an app or AI agent connects to Telegram determines what it can reach. There is a route for making calls, and two ways to receive activity, one where the bot asks for updates and one where Telegram pushes them, each carried by the same bot token.
The Bot API answers at api.telegram.org. Each method is called by name under the bot token, for example a request to sendMessage, over GET or POST, and every response is a JSON object with an ok field.
The bot calls getUpdates, and Telegram holds the request open until updates arrive or a timeout passes. It needs no public URL, which suits local development and simple deployments.
The bot registers an HTTPS URL with setWebhook, and Telegram posts each chosen update to it as it happens. A secret token header lets the receiver confirm the request came from Telegram.
A bot is created through BotFather, which issues a single token. The token is sent in the request path under bot, and it is the only credential the Bot API uses. There are no scopes: the token grants the bot every action it is capable of, and what the bot can actually do in a given chat is set by its membership and its administrator rights there.
The Telegram Bot API is split into areas an agent can act on, like sending messages, receiving updates, managing chats, sending media, and handling inline and button interactions. Each method is called by name, and a single bot token grants the bot every action it is capable of.
Send and forward text messages, edit and delete sent messages, and signal a typing or upload action in a chat.
Send photos, documents, video, and audio to a chat, and fetch a download link for a file a user sent.
Pull waiting updates over long polling, or register and inspect a webhook so Telegram pushes updates to a URL.
Read a chat and its members, leave a chat, set a chat's title, pin a message, and ban, restrict, or promote members.
Answer an inline query with results, acknowledge a button press, edit a message's text or its inline keyboard, and read the bot's own identity.
Set the list of commands the bot advertises in the Telegram client.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
MessagingSend and forward text messages, edit and delete sent messages, and signal a typing or upload action in a chat.5 | ||||||
| POST | sendMessage | Send a text message to a chat. | write | — | Current | |
The Bot API has no scopes; the bot token alone authorizes the call. The bot must be a member of a group or channel, or the user must have started the bot, for a message to be deliverable. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook event messageRate limit1 message per second per chat; 30 per second overall; 20 per minute to a group SourceOfficial documentation ↗ | ||||||
| POST | forwardMessage | Forward a message from one chat to another. | write | — | Current | |
The bot token alone authorizes the call. The bot must be able to reach both the source and the target chat. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook event messageRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | editMessageText | Edit the text of a message the bot sent. | write | — | Current | |
The bot token alone authorizes the call. A bot can edit only its own messages, within the window Telegram allows for edits. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook event edited_messageRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | deleteMessage | Delete a message. | write | — | Current | |
The bot token alone authorizes the call. A bot can delete its own messages, and others only where it has the can_delete_messages administrator right. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | sendChatAction | Show that the bot is doing something in a chat, like typing or uploading a file. | write | — | Current | |
The bot token alone authorizes the call. The status shows for a few seconds or until the next message is sent. Acts onchat action Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MediaSend photos, documents, video, and audio to a chat, and fetch a download link for a file a user sent.5 | ||||||
| POST | sendPhoto | Send a photo to a chat. | write | — | Current | |
The bot token alone authorizes the call. A file can be a new upload, a URL Telegram fetches, or a file_id Telegram already holds. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook event messageRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | sendDocument | Send a general file to a chat. | write | — | Current | |
The bot token alone authorizes the call. An uploaded file is capped at 50 MB through the Bot API. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook event messageRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | sendVideo | Send a video to a chat. | write | — | Current | |
The bot token alone authorizes the call. Telegram clients support MP4 video; other formats may be sent as a document instead. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook event messageRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | sendAudio | Send an audio file to be shown in the music player. | write | — | Current | |
The bot token alone authorizes the call. Telegram expects an MP3 or M4A file for the music player; other audio can be sent as a voice message or document. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook event messageRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | getFile | Get a download link for a file a user sent to the bot. | read | — | Current | |
Returns a file_path, which is fetched from a separate download host using the same bot token. Downloads through the Bot API are capped at 20 MB, and the link is valid for at least one hour. Acts onfile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Updates & webhooksPull waiting updates over long polling, or register and inspect a webhook so Telegram pushes updates to a URL.4 | ||||||
| POST | getUpdates | Receive incoming updates by long polling, where the request is held open until updates arrive. | read | — | Current | |
Cannot be used while a webhook is set. The allowed_updates parameter chooses which update types come back, and an offset acknowledges updates already processed. Acts onupdate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | setWebhook | Register a URL for Telegram to post incoming updates to, instead of long polling. | write | — | Current | |
The receiver URL must be HTTPS. The allowed_updates parameter chooses which update types are delivered; an empty list means all except chat_member, message_reaction, and message_reaction_count. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | deleteWebhook | Remove the webhook so the bot can switch back to long polling. | write | — | Current | |
The bot token alone authorizes the call. Returns true on success. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | getWebhookInfo | Read the current webhook status, including the URL and any pending update count. | read | — | Current | |
The bot token alone authorizes the call. Returns an empty URL when long polling is in use. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Chat managementRead a chat and its members, leave a chat, set a chat's title, pin a message, and ban, restrict, or promote members.9 | ||||||
| POST | getChat | Read up-to-date information about a chat. | read | — | Current | |
The bot token alone authorizes the call. The bot must be a member of the chat, or the user must have started it. Acts onchat Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | getChatMember | Read information about one member of a chat. | read | — | Current | |
The bot token alone authorizes the call. Returns the member's status and any administrator rights they hold. Acts onchat member Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | getChatAdministrators | List the administrators of a chat. | read | — | Current | |
The bot token alone authorizes the call. Returns each administrator and the creator, but not regular members. Acts onchat member Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | setChatTitle | Change the title of a group, supergroup, or channel. | write | — | Current | |
The bot must be an administrator with the can_change_info right. Acts onchat Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | pinChatMessage | Pin a message in a chat. | write | — | Current | |
In a group the bot must be an administrator with the can_pin_messages right, or can_edit_messages in a channel. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | banChatMember | Ban a user from a group, supergroup, or channel. | write | — | Current | |
The bot must be an administrator with the can_restrict_members right. A banned user cannot rejoin by an invite link unless unbanned first. Acts onchat member Permission (capability)None required VersionAvailable since the API’s base version Webhook event chat_memberRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | restrictChatMember | Restrict what a member can do in a supergroup, like sending messages or media. | write | — | Current | |
The bot must be an administrator with the can_restrict_members right. Passing all permissions as true lifts the restrictions. Acts onchat member Permission (capability)None required VersionAvailable since the API’s base version Webhook event chat_memberRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | promoteChatMember | Promote or demote a member's administrator rights in a chat. | write | — | Current | |
The bot must be an administrator and can only grant rights it holds itself. Passing all rights as false demotes the member. Acts onchat member Permission (capability)None required VersionAvailable since the API’s base version Webhook event chat_memberRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | leaveChat | Make the bot leave a group, supergroup, or channel. | write | — | Current | |
The bot token alone authorizes the call. After leaving, the bot can no longer send to or read the chat. Acts onchat Permission (capability)None required VersionAvailable since the API’s base version Webhook event my_chat_memberRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Inline & callbacksAnswer an inline query with results, acknowledge a button press, edit a message's text or its inline keyboard, and read the bot's own identity.4 | ||||||
| POST | answerCallbackQuery | Acknowledge a press of an inline keyboard button, optionally showing a notification. | write | — | Current | |
The bot token alone authorizes the call. A callback query should be answered, even with no text, to clear the loading state on the button. Acts oncallback query Permission (capability)None required VersionAvailable since the API’s base version Webhook event callback_queryRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | answerInlineQuery | Send results in response to a user typing the bot's name inline in any chat. | write | — | Current | |
Inline mode must be enabled for the bot with BotFather. At most 50 results are returned per query. Acts oninline query Permission (capability)None required VersionAvailable since the API’s base version Webhook event inline_queryRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | editMessageReplyMarkup | Change the inline keyboard attached to a message the bot sent. | write | — | Current | |
The bot token alone authorizes the call. A bot can edit the keyboard only on its own messages. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | getMe | Read the bot's own identity, including its username and feature flags. | read | — | Current | |
A quick way to test that the bot token is valid. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Bot configurationSet the list of commands the bot advertises in the Telegram client.1 | ||||||
| POST | setMyCommands | Set the list of commands the bot advertises in the Telegram client. | write | — | Current | |
Commands can be scoped, for example to a specific chat, chat type, or language. Acts onbot command Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Telegram can push activity to an app or AI agent as it happens, instead of the app asking again and again. The bot either calls for waiting updates over a held-open request, or registers a receiver URL that Telegram posts each update to.
| Event | What it signals | Triggered by |
|---|---|---|
message | Fires when a new incoming message of any kind arrives, like text, a photo, or a document. | In-app only |
edited_message | Fires when a message that the bot can see is edited. | In-app only |
callback_query | Fires when a user presses an inline keyboard button attached to a message. | In-app only |
inline_query | Fires when a user types the bot's name followed by a query in any chat, in inline mode. | In-app only |
my_chat_member | Fires when the bot's own membership or status in a chat changes, like being added, removed, or promoted. | In-app only |
chat_member | Fires when any member's status in a chat changes. It is delivered only when the bot is a chat administrator and chat_member is requested explicitly. | In-app only |
chat_join_request | Fires when a user requests to join a chat where the bot is an administrator with the right to manage join requests. | In-app only |
Telegram limits how fast an app or AI agent can send, with a per-chat ceiling, a per-group ceiling, and an overall broadcast ceiling, and it returns a wait time when a limit is hit rather than a hard rejection.
Telegram does not publish a single overall request quota; instead it limits sending. In a single chat a bot should send at most about one message per second, though short bursts are tolerated. In a group a bot is held to about 20 messages per minute. For bulk sending across many chats, a bot can broadcast at most about 30 messages per second by default, with higher rates available only through paid broadcasts. When a limit is exceeded the call returns HTTP 429 with a parameters object carrying retry_after, the number of seconds to wait, so an integration should pause for that long rather than retry immediately.
The Bot API has no general cursor or page parameters. Incoming updates are paged through getUpdates instead, using an offset to acknowledge updates already handled and a limit of up to 100 updates per call; once an update's id is confirmed by a higher offset, Telegram stops returning it.
An uploaded file sent through the Bot API is capped at 50 MB, and a file downloaded with getFile is capped at 20 MB. A photo sent by URL is limited to 5 MB and other files by URL to 20 MB. A text message is limited to 4,096 characters, and a media caption to 1,024 characters.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 200 | ok:false | The Bot API reports failures inside the body, not only by HTTP status. A failed call returns ok set to false, an integer error_code, and a human-readable description explaining what went wrong. | Check the ok field on every response, and read error_code and description rather than relying on the HTTP status alone. |
| 400 | Bad Request | The request was malformed or a parameter was invalid, such as a missing chat_id or a message too long to send. | Read the description, correct the named parameter, and resend. |
| 401 | Unauthorized | The bot token is missing, malformed, or has been revoked. | Check the token issued by BotFather and send it correctly in the request path. |
| 403 | Forbidden | The bot is not allowed to act here, for example the user has blocked the bot, or the bot was removed from the chat or lacks the required administrator right. | Confirm the bot is still a member with the right permissions, and stop sending to users who have blocked it. |
| 429 | Too Many Requests | A rate limit was exceeded. The response includes a parameters object with retry_after, the number of seconds to wait before trying again. | Wait the retry_after seconds before resending, and spread out sends to stay under the per-chat and broadcast limits. |
Telegram versions the Bot API by dated feature releases, like Bot API 10.1, and a method or field stays available once shipped. The newest release is 10.1.
Bot API 10.1 added support for Rich Messages, letting bots send highly structured text, with sendRichMessage and a streaming sendRichMessageDraft, plus a rich_message parameter on editMessageText. It also added support for join request queries. It was released on 11 June 2026.
Bot API 10.0 introduced guest mode, letting a bot receive certain messages and reply in chats it is not a member of, with a supports_guest_queries field on the User class. It also added the LivePhoto class and a sendLivePhoto method, and let bots see and send media in polls. It was released on 8 May 2026.
Bot API 9.6 added the Managed Bots feature and quizzes with multiple correct answers, along with further poll enhancements. It was released on 3 April 2026.
Bot API 9.3 added sendMessageDraft for streaming partial messages, and brought forum topics to private chats with a message_thread_id. It was released on 31 December 2025.
Bot API 9.0 was released on 11 April 2025, continuing the 9.x line of dated feature releases that add methods and fields without removing existing behavior.
Bot API 8.0 was released on 17 November 2024, opening the 8.x line of dated feature releases.
New releases add methods and fields; an integration keeps working and adopts new ones when it chooses.
Telegram Bot API changelog ↗Bollard AI sits between a team's AI agents and Telegram. Grant each agent exactly the access it needs, read or write, action by action, and every call is checked and logged.