Telegram Bot API
Build a Telegram bot: polling and webhooks, messages with buttons, photos and files, commands and Telegram Stars payments.
CommunicationGuided#telegram#bots#chat#messaging#webhooks#telegram-stars
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
The Telegram Bot API lets your server run a Telegram bot: receive messages, button presses and payments from users, and reply with text, buttons, photos, files, locations and invoices. It is a plain HTTPS API: every call is https://api.telegram.org/bot<token>/<methodName>, with parameters as a query string, a JSON body, a form, or multipart/form-data when you upload files. Every response is JSON with ok and either result or description plus error_code. This collection covers the calls almost every bot needs, in the order you would build one. It was checked against Bot API 10.4 (9 November 2026).
Create a bot and get its token
- In Telegram, open a chat with @BotFather (the official bot for managing bots; check the blue verified tick).
- Send
/newbot, choose a display name and a username (5-32 characters) ending inbot. The username cannot be changed later. - BotFather replies with the bot's token: digits, a colon, then a long string. Paste it into the botToken variable (marked secret).
- Open your new bot in Telegram and press Start. A bot cannot message a user who has never started it.
See Bots: an introduction and the BotFather guide.
Authentication: the token is in the URL
There is no header or OAuth: the token is part of the path (/bot<token>/getMe). Anyone who has the token fully controls the bot. That has consequences:
- URLs with the token end up in server access logs, proxy logs, browser history and error trackers. Scrub them, and never call the API from a browser or mobile app; keep calls on your server.
- File download links (
/file/bot<token>/...) contain the token too: download on the server and serve the file yourself. - If the token leaks, send
/tokento @BotFather and generate a new one, then update your server. - For webhooks, verify the
X-Telegram-Bot-Api-Secret-Tokenheader instead of putting the token in your webhook path.
How to use this collection
- Fill botToken, run getMe.
- Message your bot, run getUpdates (fills
chatId), then sendMessage. - 2. Webhooks when you deploy; 3. Messages and buttons for formatting, keyboards and edits; 4. Photos, documents and files for media; 5. Chats, members and commands; 6. Payments with Telegram Stars for selling digital goods.
Common errors
| error_code | Typical description | What to do |
|---|---|---|
| 400 | chat not found, can't parse entities, message is not modified | Check chat_id, escape HTML/MarkdownV2, or change the text before editing. |
| 401 | Unauthorized | The token is wrong or revoked: copy it again from @BotFather. |
| 403 | bot was blocked by the user | The user stopped the bot; stop messaging them. |
| 404 | Not Found | Malformed URL or method name (remember the bot prefix before the token). |
| 409 | Conflict | getUpdates while a webhook is set (delete it), or two pollers at once. |
| 429 | Too Many Requests: retry after N | Wait parameters.retry_after seconds, then retry. |
When a group is upgraded to a supergroup, errors include parameters.migrate_to_chat_id: switch to that new chat ID.
Limits and pricing
The Bot API is free. Telegram applies flood limits: roughly one message per second per chat, a lower rate inside groups, and a global cap on broadcasts unless you enable paid broadcasts; see My bot is hitting limits. Bots download files up to 20 MB and upload up to 50 MB. Digital goods are paid in Telegram Stars: see Payments in Telegram Stars. Full reference: Telegram Bot API and its changelog.
Endpoints 26
1. Start here
- GETgetMe: check the bot token
{{apiBase}}/bot{{botToken}}/getMeReturns the bot's own account (a User object with is_bot: true). It takes no parameters, so it is the simplest way to prove that botToken is correct. What… - GETgetUpdates: receive messages (long polling)
{{apiBase}}/bot{{botToken}}/getUpdatesFetches new updates (messages, button presses, payments and so on) for your bot. Open Telegram, send any message to your bot, then run this request: the… - POSTsendMessage: plain text
{{apiBase}}/bot{{botToken}}/sendMessageSends a text message to chat_id. chat_id is a number for users and groups, or @channelusername for public channels where the bot is an admin. A bot can only…
2. Webhooks
- POSTsetWebhook: register your HTTPS endpoint
{{apiBase}}/bot{{botToken}}/setWebhookTells Telegram to deliver every update as an HTTPS POST (JSON body) to url. Once set, getUpdates stops working until you delete the webhook. Why the secret… - GETgetWebhookInfo: check delivery status
{{apiBase}}/bot{{botToken}}/getWebhookInfoShows the current webhook and whether Telegram can reach it. Takes no parameters. Fields to watch: url (empty when you use getUpdates), pending_update_count… - POSTdeleteWebhook: go back to polling
{{apiBase}}/bot{{botToken}}/deleteWebhookRemoves the webhook so you can use getUpdates again (for example while developing locally). Set drop_pending_updates to true to also throw away updates that…
3. Messages and buttons
- POSTsendMessage: HTML formatting + inline keyboard
{{apiBase}}/bot{{botToken}}/sendMessageSends a formatted message with buttons under it. parse_mode HTML supports <b>, <i>, <u>, <s>, <tg-spoiler>, <a href>, <code>, <pre> and <blockquote>. Escape… - POSTsendMessage: MarkdownV2 reply to a message
{{apiBase}}/bot{{botToken}}/sendMessageSends a MarkdownV2-formatted message as a reply to an earlier message. MarkdownV2 escaping: outside formatting, each of _ * [ ] ( ) ~ > # + - = | { } . ! must… - POSTeditMessageText: change a sent message
{{apiBase}}/bot{{botToken}}/editMessageTextReplaces the text (and optionally the keyboard) of a message the bot sent, identified by chat_id + message_id (for inline-mode messages use inline_message_id… - POSTanswerCallbackQuery: acknowledge a button press
{{apiBase}}/bot{{botToken}}/answerCallbackQueryEvery callback_query must be answered, otherwise the user sees a spinner on the button. Answer as soon as you receive it, even if you have nothing to say.… - POSTsendChatAction: show "typing..."
{{apiBase}}/bot{{botToken}}/sendChatActionShows a status such as "typing..." or "sending photo..." at the top of the chat while your bot prepares a slow reply. The status lasts 5 seconds or until the… - POSTsendLocation: share a map point
{{apiBase}}/bot{{botToken}}/sendLocationSends a location pin. latitude and longitude are required floats. Optional: horizontal_accuracy (0-1500 metres) and live_period (60-86400 seconds) to send a… - POSTforwardMessage: forward with attribution
{{apiBase}}/bot{{botToken}}/forwardMessageForwards a message from from_chat_id to chat_id. The copy shows "Forwarded from ...". Service messages and messages with protected content cannot be… - POSTcopyMessage: copy without the forward header
{{apiBase}}/bot{{botToken}}/copyMessageLike forwardMessage, but the copy has no link to the original and you can replace the caption (caption, parse_mode) and add reply_markup. Use it to re-post… - POSTdeleteMessage: remove a message
{{apiBase}}/bot{{botToken}}/deleteMessageDeletes a message. Limits: it must be less than 48 hours old; in private chats the bot can delete its own messages and the user's incoming ones; in groups it…
4. Photos, documents and files
- POSTsendPhoto: by URL
{{apiBase}}/bot{{botToken}}/sendPhotoSends a photo that Telegram downloads from a public photo URL (up to 5 MB this way). caption is 0-1024 characters and accepts parse_mode. Three ways to send… - POSTsendPhoto: upload a file (multipart)
{{apiBase}}/bot{{botToken}}/sendPhotoUploads a photo from your computer. The body must be multipart/form-data (JSON cannot carry files): pick the image in the photo field. Photos up to 10 MB;… - POSTsendDocument: upload a file
{{apiBase}}/bot{{botToken}}/sendDocumentSends any file as a document (no compression), up to 50 MB by upload. Sending a document by URL only works for PDF and ZIP files. Optional thumbnail (JPEG… - POSTsendMediaGroup: album of 2-10 photos
{{apiBase}}/bot{{botToken}}/sendMediaGroupSends 2-10 items as one album. media is an array of InputMediaPhoto (or video, document, audio) objects, each with type and media; only the first item's… - GETgetFile: get a download path
{{apiBase}}/bot{{botToken}}/getFileTurns a file_id (from a message a user sent, or saved by the requests above) into a file_path you can download. Bots can download files up to 20 MB this way.… - GETDownload the file
{{apiBase}}/file/bot{{botToken}}/{{filePath}}Downloads the file bytes from https://api.telegram.org/file/bot<token>/<file_path> using the filePath saved by getFile. This is not a Bot API method, so the…
5. Chats, members and commands
- GETgetChat: full chat details
{{apiBase}}/bot{{botToken}}/getChatReturns a ChatFullInfo object for a user, group, supergroup or channel: id, type, title or name, username, and for groups extras such as description,… - GETgetChatMember: is this user a member or admin?
{{apiBase}}/bot{{botToken}}/getChatMemberReturns one member of a group or channel, with status: creator, administrator, member, restricted, left or kicked. Use it to check whether someone joined your… - POSTsetMyCommands: set the command menu
{{apiBase}}/bot{{botToken}}/setMyCommandsSets the list of commands shown in the menu button and when users type /. Up to 100 commands; each command is 1-32 characters of lowercase letters, digits and…
6. Payments with Telegram Stars
- POSTsendInvoice: Telegram Stars invoice
{{apiBase}}/bot{{botToken}}/sendInvoiceSends an invoice the user can pay with Telegram Stars. For digital goods and services, Telegram requires Stars: set currency to XTR, pass an empty… - POSTanswerPreCheckoutQuery: approve or decline
{{apiBase}}/bot{{botToken}}/answerPreCheckoutQueryConfirms that you can still fulfil the order (stock, price, account state) before Telegram charges the user. You must answer within 10 seconds of the…
API details
- Base URL
https://api.telegram.org- Authentication
- A provider-specific scheme
- Operations
- 26 operations on 26 pathsPOST 19GET 7
- Main resources
- 1. Start here 32. Webhooks 33. Messages and buttons 94. Photos, documents and files 65. Chats, members and commands 36. Payments with Telegram Stars 2
- Description format
- Swastik Codes guided collection, API version
checked against the docs on 2026-11-17 - Links
- Documentation
How to test the Telegram Bot API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Telegram Bot API collection, without the publisher's secrets.
- Add your credentialsThis API uses A provider-specific scheme. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “getMe: check the bot token” (GET {{apiBase}}/bot{{botToken}}/getMe), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Telegram Bot API?
Build a Telegram bot: polling and webhooks, messages with buttons, photos and files, commands and Telegram Stars payments. It is listed under Communication and has 26 endpoints.
Who publishes the Telegram Bot API?
It is listed from Telegram's public API description (an OpenAPI document), not published by Telegram on Swastik Codes. Anyone who controls telegram.org can claim the profile by adding a DNS TXT record.
What is the base URL of the Telegram Bot API?
Requests go to https://api.telegram.org. Endpoint paths are added to this base URL.
How do I authenticate with the Telegram Bot API?
With A provider-specific scheme.
How many endpoints does the Telegram Bot API have?
26 operations on 26 paths (19 POST, 7 GET). The largest groups are 1. Start here, 2. Webhooks, 3. Messages and buttons, 4. Photos, documents and files.
Is forking the Telegram Bot API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.