Telegram Bot API
The Telegram Bot API is a free, REST-based interface for building feature-rich bots on Telegram — messaging, media sharing, inline queries, payments, Mini Apps, and the all-new bot-to-bot communication (2026).
API Overview
Bot API 10.x · 2026The Telegram Bot API is a free, HTTP-based REST interface that lets developers create bots for Telegram. Bots can send and receive text, media, documents, and rich interactive messages. They can operate in private chats, groups, and channels. The API supports two update delivery modes: Webhooks (push-based) and Long Polling (pull-based).
New in 2026 (Bot API 10.1–10.3): Bot-to-Bot communication (multi-agent workflows), Guest Mode (@mention without joining a group), Rich Messages (tables, math expressions, spoilers), Managed Bots (create and manage bots from within bots), and expanded Mini Apps capabilities.
API Features
| Feature | Description | Status |
|---|---|---|
| Text Messages | Send/receive text with Markdown, HTML, MarkdownV2, and rich formatting | Available |
| Media Messages | Send photos, videos, audio, voice notes, documents, stickers, animations | Available |
| Inline Keyboards | Interactive buttons attached to messages — URL, callback, switch inline, etc. | Available |
| Inline Mode | Omnipresent bot access — users can query your bot inline from any chat | Available |
| Webhooks | Real-time HTTPS push delivery of bot updates | Available |
| Payments API | Accept payments via Telegram's built-in payment system (Telegram Stars) | Available |
| Mini Apps | Embedded web apps (HTML/CSS/JS) running in Telegram WebView | Available |
| Bot-to-Bot Communication | Bots can message and coordinate with other bots (multi-agent) | New May 2026 |
| Guest Mode | Bots can be @mentioned in groups without needing to join them | New 2026 |
| Managed Bots | Create, update tokens, and manage other bots programmatically | New 2026 |
| Rich Messages | Tables, math expressions, spoilers, expandable blockquotes | New 2026 |
| Privacy Mode | Bots only receive messages they're directly addressed in groups (default on) | Available |
Rate Limits (Messaging)
| Context | Limit | Notes |
|---|---|---|
| To Different Users | 30 messages / second | Standard broadcast rate |
| To the Same Group / Chat | 20 messages / minute | Anti-flood protection |
| To the Same Individual Chat | 1 message / second | Per individual chat conversation |
| Paid Broadcasts | Up to 1,000 messages / second | 0.1 Telegram Stars per message beyond free limit — enable via @BotFather |
| Incoming Updates | No documented hard limit | Use webhooks for high-throughput handling |
Rate limit violations return HTTP 429 (Too Many Requests) with a retry_after field in the response body. Honor this value before retrying — implement a message queue for high-volume bots.
File Size Limits
| Limit Type | Standard Bot API | Local Bot API Server |
|---|---|---|
| Upload (sendDocument, sendVideo, etc.) | 50 MB | 2 GB |
| Download (getFile) | 20 MB | 2 GB |
| Photo (sendPhoto) | Up to 10 MB (JPEG); Telegram may compress larger images | 2 GB |
| Animation / GIF | 50 MB | 2 GB |
Local Bot API Server: For files larger than 50 MB, Telegram provides an open-source Local Bot API Server that you can self-host. It supports files up to 2 GB and allows custom webhook ports (up to 100,000 concurrent connections).
Supported Media Types
| Type | Formats / Notes |
|---|---|
| Photos | JPEG, PNG, WebP — Telegram may compress; send as Document to preserve quality |
| Videos | MP4 (H.264) recommended. MOV, AVI also accepted but may be re-encoded |
| Audio | MP3, M4A, OGG, FLAC, WAV — for voice notes use OGG/OPUS |
| Documents | Any file type up to the size limit — sent without modification or compression |
| Stickers | WebP (static), TGS (Telegram animated), WEBM (video stickers) |
Authentication
Simple Authentication: Telegram bots do not use OAuth 2.0. Instead, you receive a unique Bot Token from @BotFather when you create your bot. All API requests use this token directly in the URL — no user authorization flows needed.
| Requirement | Details |
|---|---|
| Auth Method | Bot Token (issued by @BotFather on Telegram) |
| How to Create a Bot | Message @BotFather on Telegram → /newbot command → receive Bot Token |
| API Endpoint Format | https://api.telegram.org/bot<TOKEN>/METHOD_NAME |
| Transport Security | All requests must be made over HTTPS |
| Token Security | Treat your Bot Token like a password. Never expose it in client-side code or public repositories. |
| No App Review | No formal app review process — bots are available immediately after creation |
Quick Start Guide
Create Your Bot via @BotFather
Open Telegram, search for @BotFather, send /newbot, and follow the prompts. You'll receive your Bot Token.
Send Your First Message
GET https://api.telegram.org/bot{YOUR_BOT_TOKEN}/sendMessage
?chat_id=TARGET_CHAT_ID
&text=Hello+from+my+bot%21
&parse_mode=MarkdownV2Set Up a Webhook for Real-Time Updates
POST https://api.telegram.org/bot{YOUR_BOT_TOKEN}/setWebhook
Content-Type: application/json
{
"url": "https://your-server.com/webhook",
"allowed_updates": ["message", "callback_query", "inline_query"]
}Telegram will POST JSON update objects to your webhook URL for every event.
Send a Photo with a Caption
POST https://api.telegram.org/bot{YOUR_BOT_TOKEN}/sendPhoto
Content-Type: multipart/form-data
chat_id: TARGET_CHAT_ID
photo: [binary file data or photo URL]
caption: Caption text hereGet Bot Info
GET https://api.telegram.org/bot{YOUR_BOT_TOKEN}/getMeReturns your bot's username, ID, and capabilities. Useful for verifying your token is working.
Common Errors & Solutions
| Error | Meaning | Common Cause | Solution |
|---|---|---|---|
| 401 Unauthorized | Invalid bot token | Token is wrong, expired, or revoked | Verify token with /getMe. Regenerate via @BotFather if needed. |
| 400 Bad Request | Invalid parameter | Wrong chat_id format, invalid parse_mode, or missing required field | Validate all parameters. Check chat_id exists and bot has permission to message it. |
| 403 Forbidden | Bot blocked or kicked | User blocked the bot or bot was removed from the group | Catch this error and remove the user from your active user list. |
| 429 Too Many Requests | Rate limit exceeded | Sending too many messages too quickly | Read the retry_after field and wait that many seconds before retrying. Implement a message queue. |
| 413 Request Entity Too Large | File too large | Uploading a file exceeding the 50 MB limit | Compress the file or set up a Local Bot API Server for the 2 GB limit. |
Best Practices
Use Webhooks, Not Polling
For production bots, always use Webhooks for real-time updates. Long polling is only suitable for development/testing environments.
Queue High-Volume Messages
For broadcasting to many users, use a message queue (e.g., Redis Queue) to send at 25–28 msg/sec — safely below the 30/sec limit.
Send as Document for Quality
To preserve original image/video quality without Telegram compression, send media as a Document rather than a photo or video.
Protect Your Bot Token
Never expose the Bot Token in client-side code or public code repositories. Store it in environment variables or a secrets manager.
Validate Webhook Source
Verify incoming webhook requests are from Telegram by checking the secret token header (set during setWebhook) or by IP allowlisting Telegram's IP ranges.
Self-Host for Large Files
If you need to handle files larger than 50 MB, deploy Telegram's open-source Local Bot API Server — it removes the standard size limits (supports up to 2 GB).