> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agno.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Telegram
> Expose agents, teams, or workflows as Telegram bots with webhook endpoints.
The Telegram interface exposes an Agno Agent, Team, or Workflow on Telegram via FastAPI webhook endpoints. It handles inbound messages (text, photos, audio, video, documents, stickers) and streams responses back to the originating chat.
## Setup
Follow the [Telegram deploy guide](/deploy/interfaces/telegram/overview) to set up your bot.
Required configuration:
* `TELEGRAM_TOKEN` (bot token from @BotFather)
* `TELEGRAM_WEBHOOK_SECRET_TOKEN` -- required in production, skipped when `APP_ENV=development`
* An ngrok tunnel (for local development) and webhook pointing to `/telegram/webhook`
## Example Usage
Create an agent, expose it with the `Telegram` interface, and serve via `AgentOS`:
```python basic.py theme={null}
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.google import Gemini
from agno.os.app import AgentOS
from agno.os.interfaces.telegram import Telegram
agent_db = SqliteDb(session_table="telegram_sessions", db_file="tmp/telegram_basic.db")
telegram_agent = Agent(
name="Telegram Bot",
model=Gemini(id="gemini-2.5-pro"),
db=agent_db,
instructions=[
"You are a helpful assistant on Telegram.",
"Keep responses concise and friendly.",
],
add_history_to_context=True,
num_history_runs=3,
add_datetime_to_context=True,
markdown=True,
)
agent_os = AgentOS(
agents=[telegram_agent],
interfaces=[Telegram(agent=telegram_agent)],
)
app = agent_os.get_app()
if __name__ == "__main__":
agent_os.serve(app="basic:app", port=7777, reload=True)
```
See the [Telegram examples](/agent-os/usage/interfaces/telegram/basic) for more usage patterns including [streaming](/agent-os/usage/interfaces/telegram/streaming), [teams](/agent-os/usage/interfaces/telegram/team), [workflows](/agent-os/usage/interfaces/telegram/workflow), and [multiple instances](/agent-os/usage/interfaces/telegram/multiple-instances).
## Parameters
Provide `agent`, `team`, or `workflow`. Call `get_router()` to get the FastAPI `APIRouter` with all endpoints attached.
| Parameter | Type | Default | Description |
| ------------------------ | ---------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agent` | `Optional[Agent]` | `None` | Agno `Agent` instance. |
| `team` | `Optional[Team]` | `None` | Agno `Team` instance. |
| `workflow` | `Optional[Workflow]` | `None` | Agno `Workflow` instance. |
| `prefix` | `str` | `"/telegram"` | Custom FastAPI route prefix for the Telegram interface. |
| `tags` | `Optional[List[str]]` | `None` | FastAPI route tags for API documentation. Defaults to `["Telegram"]` if not provided. |
| `token` | `Optional[str]` | `None` | Bot token. Falls back to `TELEGRAM_TOKEN` environment variable. |
| `streaming` | `bool` | `True` | Enable token-by-token streaming with live message edits. |
| `show_reasoning` | `bool` | `False` | Show the model's reasoning as a blockquote message. Works in both streaming and non-streaming modes. |
| `reply_to_mentions_only` | `bool` | `True` | When `True` (default), bot responds to @mentions and replies in groups, and all messages in DMs. When `False`, responds to all messages in groups. |
| `reply_to_bot_messages` | `bool` | `True` | When `True`, also responds when users reply to the bot's own messages in groups. |
| `start_message` | `str` | `"Hello! I'm ready to help..."` | Message sent in response to the `/start` command. |
| `help_message` | `str` | `"Send me text, photos..."` | Message sent in response to the `/help` command. |
| `error_message` | `str` | `"Sorry, there was an error..."` | Message sent when processing fails. |
| `new_message` | `str` | `"New conversation started..."` | Message sent when a user starts a new session with `/new`. |
| `commands` | `Optional[List[Dict]]` | `None` | List of bot commands to register with Telegram. Each dict has `command` and `description` keys. Defaults to `/start`, `/help`, and `/new` when not provided. |
| `register_commands` | `bool` | `True` | Automatically register commands with the Telegram Bot API on first message. |
## Endpoints
Mounted under the `/telegram` prefix (customizable via `prefix`):
### `GET /telegram/status`
Health/status check for the interface. Returns `{"status": "available"}`.
### `POST /telegram/webhook`
Receives Telegram updates (messages, edited messages).
* Validates the `X-Telegram-Bot-Api-Secret-Token` header; bypassed when `APP_ENV=development`.
* Deduplicates updates by `update_id`.
* Processes text, photos, voice notes, audio, video, documents, stickers, and animations.
* Streams or sends responses back to the originating chat (splits long messages at Telegram's 4096 character limit).
* Responses: `200 {"status": "processing"}` or `{"status": "ignored"}`, `403` invalid secret token, `500` errors.
## Behavior
### Session Management
Sessions are scoped by chat and entity. The `entity_id` is the agent, team, or workflow ID (falls back to name, then type).
* **DMs and basic groups**: `tg:Telegram Bot:123456789`
* **Supergroup threads and forum topics**: `tg:Telegram Bot:123456789:42`
When a database is configured on the agent/team, the `/new` command creates a fresh session. Without a database, sessions reset on server restart. History and memory are not persisted.
The `/new` command only works when a database is configured. Without a database, each server restart already starts a fresh session.
### Streaming
When `streaming=True` (the default), the bot edits the response message in real time as tokens arrive. Edits are throttled to roughly once per second to stay within Telegram's rate limits. The user sees incremental output instead of waiting for the full response.
For workflows, streaming also surfaces step progress (e.g., which agent in the workflow is currently running).
### Group Chat Support
By default, the bot only responds when mentioned (`@your_bot`) or replied to in group chats. This is controlled by two parameters:
* `reply_to_mentions_only=True` (default): only respond to @mentions and direct replies
* `reply_to_bot_messages=True` (default): also respond when users reply to the bot's own messages
To have the bot respond to all messages in a group, set `reply_to_mentions_only=False`.
**BotFather privacy mode:** By default, Telegram bots in groups only receive messages that mention them or are commands. To let the bot see all group messages (required for `reply_to_mentions_only=False`), message @BotFather, send `/setprivacy`, select your bot, and choose **Disable**.
### Media Support
**Inbound** (user sends to bot): photos, stickers, voice notes, audio files, video, video notes, animations (GIFs), and documents. Media is downloaded and passed to the agent as images, audio, video, or file inputs.
**Outbound** (agent sends to user): images, audio, video, and files generated by agent tools (e.g., DALL-E, ElevenLabs). Media is sent as native Telegram media messages alongside the text response.
## TelegramTools
`TelegramTools` is a standalone toolkit that lets agents proactively send messages and media to Telegram chats. It is independent from the Telegram interface. The interface handles inbound webhooks; the toolkit gives agents outbound actions.
```python theme={null}
from agno.tools.telegram import TelegramTools
agent = Agent(
tools=[TelegramTools(chat_id="123456789", all=True)],
)
```
### Toolkit Parameters
| Parameter | Type | Default | Description |
| ----------------------- | --------------- | ------- | ---------------------------------------------------------- |
| `chat_id` | `Optional[str]` | `None` | Default chat ID. Falls back to `TELEGRAM_CHAT_ID` env var. |
| `token` | `Optional[str]` | `None` | Bot token. Falls back to `TELEGRAM_TOKEN` env var. |
| `enable_send_message` | `bool` | `True` | Enable `send_message` tool. |
| `enable_send_photo` | `bool` | `False` | Enable `send_photo` tool. |
| `enable_send_document` | `bool` | `False` | Enable `send_document` tool. |
| `enable_send_video` | `bool` | `False` | Enable `send_video` tool. |
| `enable_send_audio` | `bool` | `False` | Enable `send_audio` tool. |
| `enable_send_animation` | `bool` | `False` | Enable `send_animation` tool (GIFs). |
| `enable_send_sticker` | `bool` | `False` | Enable `send_sticker` tool. |
| `enable_edit_message` | `bool` | `False` | Enable `edit_message` tool. |
| `enable_delete_message` | `bool` | `False` | Enable `delete_message` tool. |
| `all` | `bool` | `False` | Enable all tools. Overrides individual flags. |
### Toolkit Methods
| Method | Description |
| ---------------- | ----------------------------------------------------------- |
| `send_message` | Send a text message to a chat. |
| `send_photo` | Send a photo (bytes) with optional caption. |
| `send_document` | Send a document (bytes) with filename and optional caption. |
| `send_video` | Send a video (bytes) with optional caption. |
| `send_audio` | Send an audio file (bytes) with optional caption and title. |
| `send_animation` | Send an animation/GIF (bytes) with optional caption. |
| `send_sticker` | Send a sticker (bytes). |
| `edit_message` | Edit a previously sent message by `message_id`. |
| `delete_message` | Delete a message by `message_id`. |
All methods return a JSON string with `{"status": "success", "message_id": ...}` on success or `{"status": "error", "message": ...}` on failure.
For the full toolkit reference, see [TelegramTools](/tools/toolkits/social/telegram).
## Testing the Integration
1. Run the app locally: `python .py` (ensure ngrok is running)
2. Register the webhook: `curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=${NGROK_URL}/telegram/webhook"`
3. Open your bot in Telegram and send `/start` or any message
4. In a group: add the bot and mention it with `@your_bot hello`
## Troubleshooting
| Symptom | Cause | Fix |
| --------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| 403 errors on webhook | Running in production mode without a webhook secret | Set `APP_ENV=development` for local testing, or set `TELEGRAM_WEBHOOK_SECRET_TOKEN` and register the webhook with the matching `secret_token` |
| No response from the bot | Server not running or webhook not set | Check server: `curl http://localhost:7777/telegram/status`. Check webhook: `curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/getWebhookInfo"` |
| Bot ignores group messages | Privacy mode enabled (default) | Message @BotFather, send `/setprivacy`, select your bot, choose **Disable** |
| `/new` has no effect | No database configured | Add a `SqliteDb` (or other DB) to the agent/team. Without a DB, sessions are ephemeral and `/new` cannot create a new one. |
| `TELEGRAM_TOKEN is not set` | Missing env var | Export `TELEGRAM_TOKEN` before running |
## Developer Resources
* [Telegram deploy guide](/deploy/interfaces/telegram/overview)
* [Telegram examples](/agent-os/usage/interfaces/telegram/basic)
* [TelegramTools reference](/tools/toolkits/social/telegram)
* [Deployment templates](/deploy/templates)