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.

Isolated tests: APP_ENV=development bypasses validation and logs a warning. Keep it unset for public tunnels and deployed webhooks; configure the secret on both the server and setWebhook.

Message Processing

Step	Behavior
Deduplication	Per-instance, in-process `update_id` cache for 60 seconds. This is not durable or shared across replicas.
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

The interface constructs session keys using the chat and optional topic:

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}`

Current stored-session lookup uses a prefix comparison without a delimiter boundary. For the same user and entity, a scope such as tg:a:12 can select a stored tg:a:123 session. Persistent multi-chat deployments therefore do not yet have strict chat isolation from this lookup. An upstream fix is required before relying on that guarantee.

Streaming Events

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

Event	Display
`ReasoningStarted`	"Reasoning..."
`ToolCallStarted`	"{ToolName}..."
`ToolCallCompleted`	"{ToolName}" (trailing ellipsis removed)
`ToolCallError`	"{ToolName} failed"
`RunContent`	Accumulated content, edited every 1.0s
`MemoryUpdateStarted`	"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`	Network-reachable webhooks	Webhook validation secret. Bypassed when `APP_ENV=development`.
`APP_ENV`	No	Use `development` only for isolated non-network tests; it disables webhook verification.