# Telegram Bot API (slim)

> The Telegram Bot API is Telegram's HTTP interface for bot accounts. A bot sends and edits messages, media and polls, manages chats and takes payments, and receives user messages by long polling or webhook, with a token issued by @BotFather.

- Full: https://www.anchorterminal.com/tools/telegram-bot.md (~7,650 tokens) · this version ~1,830 tokens · JSON https://www.anchorterminal.com/tools/telegram-bot.json · canonical https://www.anchorterminal.com/tools/telegram-bot
- Index: https://www.anchorterminal.com/llms.txt · API: https://www.anchorterminal.com/api/v1/index.json · Updated: 2026-10-10

**E · 43/100 · rank #885 of 950 · #14 in Messaging APIs · not agent-ready · confidence medium**


Assessment: Telegram's first-party bot interface is free, needs no card and documents 185 methods on one page with a dated changelog and numeric send limits. No OpenAPI document, status page, SLA or idempotency key was found, one token controls the whole bot and travels in the URL, and a person must create the bot in a chat with @BotFather.

## Facts

- Kind: HTTP API · vendor: Telegram Messenger Inc. · category: Messaging APIs · legal entity: Telegram Messenger Inc. · provenance 74/100
- Endpoint: `https://api.telegram.org` (HTTP)
- Auth: API key · pricing: Free · x402: no · licence: Proprietary hosted service under the Telegram Bot Platform Developer Terms of Service. The Bot API server source in tdlib/telegram-bot-api is BSL-1.0
- Probe metrics: not measured yet (probes haven't run)
- API: HTTPS at https://api.telegram.org/bot<token>/METHOD_NAME, version 10.3 of 24 August 2026. 185 methods and about 400 types. GET or POST, with parameters as query string, form, JSON or multipart. Method names are case-insensitive
- Access: Self-serve. A person sends `/newbot` to @BotFather in Telegram and receives the token. A user must start the bot or add it to a group before it can message them
- Credentials: One token per bot in the URL path, with no scopes or expiry. `/token` in @BotFather generates a new one. Managed bots have `getManagedBotToken` and `replaceManagedBotToken`
- Inbound: `getUpdates` long polling (1 to 100 updates a call, `offset`, `timeout`, `allowed_updates`) or a webhook set with `setWebhook`. The two are mutually exclusive, and updates are kept at most 24 hours
- Webhooks: HTTPS with TLS 1.2 or later on ports 443, 80, 88 or 8443, from 149.154.160.0/20 and 91.108.4.0/22. Optional `secret_token` returned in `X-Telegram-Bot-Api-Secret-Token`. Self-signed certificates can be uploaded
- Rate limits: About one message a second per chat with short bursts, 20 messages a minute in a group, about 30 messages a second in bulk. Paid broadcasts raise bulk sends to 1,000 a second
- Errors: JSON with `ok`, `error_code` and `description`, plus optional `parameters` holding `retry_after` or `migrate_to_chat_id`. The reference says `error_code` contents are subject to change. No error list is published
- Files: Downloads up to 20 MB with `getFile` and uploads up to 50 MB on the hosted API. A local server lifts uploads to 2,000 MB and removes the download limit
- Group privacy: Privacy mode is on by default, so a bot in a group receives only commands, replies to it and service messages unless it is an admin or the mode is disabled in @BotFather
- Fees: Free. Paid broadcasts cost 0.1 Stars per message above 30 a second and need 100,000 Stars and 100,000 monthly active users. Digital goods must be sold in Telegram Stars, and Stars sales carry a 15 per cent fee while topics in private chats are enabled
- Test environment: A separate environment with its own accounts and bots, called at https://api.telegram.org/bot<token>/test/METHOD_NAME
- Self-hosting: tdlib/telegram-bot-api, C++, BSL-1.0, version 10.3, last commit 25 August 2026. Needs an `api_id` and `api_hash` from Telegram, and the bot must call `logOut` on the hosted server first
- Support: @BotSupport in Telegram, announcements on @BotNews and discussion in @BotTalk. @BotFather sends status alerts to popular bots whose reply rate drops
- Data handling: Privacy policy section 6 lists what bots receive. Data for UK and EEA sign-ups is stored in the Netherlands. Group companies in the British Virgin Islands and Dubai are named. No DPA or sub-processor list was found
- Status: No public status page, incident history or SLA was found

- Scores: Reliability 40, Performance pending, Schema & documentation 44, Agent ergonomics 48, Security & auth 35, Payments & pricing 40, Task success pending, Maintenance & community 38, Transparency & trust 64 · total over the 7 assessed categories
- Why: Reliability, Graded on the hosted API at api.telegram.org, with the hosted lines. · Schema & documentation, No OpenAPI document or other machine-readable contract is published by Telegram (0). · Agent ergonomics, Responses are whole `Message` or `Update` objects with no field selection. · Security & auth, One token per bot gives full control, issued and regenerated in @BotFather with `/token`. · Payments & pricing, No x402, MPP or L402 in the reference, the FAQ, the developer terms or the server source (0). · Maintenance & community, Closed service with an open-source server. · Transparency & trust, Editorial half only.
- Sources: 16, open questions: 10, both in the full twin
- Capabilities: messaging.inbound
- JSON: https://www.anchorterminal.com/api/v1/tools/telegram-bot.json
- Verify (for the vendor): the badge `https://www.anchorterminal.com/badges/telegram-bot.svg` or a link to https://www.anchorterminal.com/tools/telegram-bot from a page on telegram.org or one of its subdomains, or the README of github.com/tdlib/telegram-bot-api, then `POST https://www.anchorterminal.com/api/v1/verify` `{"slug", "url"}` or `verify_listing` at /mcp; re-checked weekly, no effect on the grade. Snippets in the full twin.

## Before you call it

1. Send `POST https://api.telegram.org/bot<token>/sendMessage` with `chat_id` and `text`. Keep the token out of logs, because it is part of the URL.
2. On HTTP 429 wait the `parameters.retry_after` seconds before retrying. Stay under one message a second per chat and 20 a minute per group.
3. Call `getUpdates` with `offset` set to the last `update_id` plus one, or the same updates return. Updates are kept for at most 24 hours.
4. A retried send can post twice, as there is no idempotency key. Record the returned `message_id` before retrying after a timeout.
5. In groups the bot sees only commands and replies unless privacy mode is disabled in @BotFather or the bot is an admin.

## Connect

```bash
curl https://api.telegram.org/bot<token>/getMe
```
Full config and headless snippets are in the full page. Through letme (picks today, calling later): https://letme.dev/telegram-bot

## Similar tools

| Tool | Grade | Score | Shared capabilities | Slim |
| --- | --- | --- | --- | --- |
| Twilio API + MCP | A | 80.4 | messaging.inbound | https://www.anchorterminal.com/tools/twilio.min.md |
| Bird API + MCP | BB | 76.5 | messaging.inbound | https://www.anchorterminal.com/tools/bird.min.md |
| AWS End User Messaging | BB | 74.3 | messaging.inbound | https://www.anchorterminal.com/tools/aws-end-user-messaging.min.md |
| Telnyx API + MCP | BB | 73.6 | messaging.inbound | https://www.anchorterminal.com/tools/telnyx.min.md |
| MailSlurp | B | 68.4 | messaging.inbound | https://www.anchorterminal.com/tools/mailslurp.min.md |


## Panel reviews (0, desk reviews from public material, no calls made)