Telegram Reference

Interface Parameters

Pass one of agent, team, or workflow to the Telegram constructor.

from agno.os.interfaces.telegram import Telegram

Telegram(agent=my_agent, streaming=True, prefix="/telegram")

Parameter	Type	Default	Description
`agent`	`Optional[Union[Agent, RemoteAgent]]`	`None`	Agno `Agent` or `RemoteAgent` instance.
`team`	`Optional[Union[Team, RemoteTeam]]`	`None`	Agno `Team` or `RemoteTeam` instance.
`workflow`	`Optional[Union[Workflow, RemoteWorkflow]]`	`None`	Agno `Workflow` or `RemoteWorkflow` instance.
`prefix`	`str`	`"/telegram"`	URL prefix for Telegram endpoints (e.g., `/telegram/webhook`).
`tags`	`Optional[List[str]]`	`["Telegram"]`	FastAPI route tags for API documentation.
`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`	Send the model’s reasoning as a separate message before the response. Non-streaming mode only.
`reply_to_mentions_only`	`bool`	`True`	In groups, respond only to @mentions and replies to the bot. In DMs, always respond.
`reply_to_bot_messages`	`bool`	`True`	Respond when users reply to the bot’s own messages in groups.
`start_message`	`str`	`"Hello! I'm ready..."`	Message sent for `/start` command.
`help_message`	`str`	`"Send me text..."`	Message sent for `/help` command.
`error_message`	`str`	`"Sorry, error..."`	Message sent when processing fails.
`new_message`	`str`	`"New conversation..."`	Message sent for `/new` command (requires database).
`commands`	`Optional[List[Dict]]`	See below	Bot commands to register. Each dict has `command` and `description` keys.
`register_commands`	`bool`	`True`	Register commands with Telegram Bot API on first message.
`quoted_responses`	`bool`	`False`	Bot replies quote the user’s message (reply-to behavior).

Default commands:

[
    {"command": "start", "description": "Start the bot"},
    {"command": "help", "description": "Show help"},
    {"command": "new", "description": "Start a new conversation"},
]

Endpoints

`POST {prefix}/webhook`

Receives Telegram updates (messages, edited messages, media).

Status	Response	Description
200	`{"status": "processing"}`	Message accepted for background processing.
200	`{"status": "duplicate"}`	Webhook retry detected (ignored).
200	`{"status": "ignored"}`	Not a message event (callback query, etc.).
403	Error	Invalid `X-Telegram-Bot-Api-Secret-Token` header.
500	Error	Processing error, or `TELEGRAM_WEBHOOK_SECRET_TOKEN` not set in production.

`GET {prefix}/status`

Health check. Returns {"status": "available"}.

Security

Webhook requests must include the X-Telegram-Bot-Api-Secret-Token header, validated against TELEGRAM_WEBHOOK_SECRET_TOKEN using constant-time comparison. Development mode: Set APP_ENV=development to bypass validation (logs a warning).

Message Processing

Step	Behavior
Deduplication	Updates tracked by `update_id` for 60 seconds. Retries ignored.
Bot filtering	Messages from other bots ignored.
Group filtering	When `reply_to_mentions_only=True`, only process @mentions and replies to the bot.
Command handling	`/start`, `/help`, `/new` handled with configurable messages.
Text cleanup	Bot mentions stripped from message text before passing to agent.
Media processing	Photos, voice, audio, video, documents, stickers, animations downloaded (max 20 MB).

Session Scope

Session IDs are scoped to prevent cross-chat context leakage:

Chat Type	Session Scope Format
DMs, basic groups	`tg:{entity_id}:{chat_id}`
Supergroup threads, forum topics	`tg:{entity_id}:{chat_id}:{message_thread_id}`

Streaming Events

When streaming=True, the interface dispatches real-time status updates:

Event	Display
`reasoning_started`	”Reasoning…”
`tool_call_started`	”…”
`tool_call_completed`	"" (trailing ellipsis removed)
`tool_call_error`	” failed”
`run_content`	Accumulated content, edited every 1.0s
`memory_update_started`	”Updating memory…”

Workflow events: Step names, loop iterations, and parallel execution status shown with indentation. Rate limiting: Respects Telegram’s 429 retry_after field. Pauses edits during rate-limit periods.

Text Formatting

Markdown is converted to Telegram HTML:

Markdown	Telegram HTML
`bold`	`<b>bold</b>`
`italic`	`<i>italic</i>`
`__underline__`	`<u>underline</u>`
`~~strike~~`	`<s>strike</s>`
`code`	`<code>code</code>`
```lang\ncode\n```	`<pre><code class="language-lang">code</code></pre>`
`> quote`	`<blockquote>quote</blockquote>`
`[text](url)`	`<a href="url">text</a>`
`- item`	`• item`

Messages exceeding 4096 characters are automatically split.

Media Support

Input (from users):

Type	Converted To
Photos, Stickers	`Image`
Voice, Audio	`Audio`
Video, Animation, Video Note	`Video`
Documents	`File`

Max download size: 20 MB. Output (from agent): Images, audio, videos, and files sent via respective Telegram API methods.

Environment Variables

Variable	Required	Description
`TELEGRAM_TOKEN`	Yes	Bot token from @BotFather. Can also pass via `token` parameter.
`TELEGRAM_WEBHOOK_SECRET_TOKEN`	Production	Webhook validation secret. Bypassed when `APP_ENV=development`.
`APP_ENV`	No	Set to `development` to bypass webhook secret validation.

Get Started

AgentOS

Example Usage

Telegram Reference

Interface Parameters

Endpoints

`POST {prefix}/webhook`

`GET {prefix}/status`

Security

Message Processing

Session Scope

Streaming Events

Text Formatting

Media Support

Environment Variables

Developer Resources

Telegram Guide

TelegramTools

​Interface Parameters

​Endpoints

​POST {prefix}/webhook

​GET {prefix}/status

​Security

​Message Processing

​Session Scope

​Streaming Events

​Text Formatting

​Media Support

​Environment Variables

​Developer Resources

Telegram Guide

TelegramTools

Interface Parameters

Endpoints

`POST {prefix}/webhook`

`GET {prefix}/status`

Security

Message Processing

Session Scope

Streaming Events

Text Formatting

Media Support

Environment Variables

Developer Resources