Telegram

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 setup guide to set up your bot.

Install dependencies: uv pip install 'agno[os,telegram]' google-genai openai

Required configuration:

• TELEGRAM_TOKEN (bot token from @BotFather)
• TELEGRAM_WEBHOOK_SECRET_TOKEN. Required in production and skipped when APP_ENV=development
• GOOGLE_API_KEY for the Gemini model in the interface example
• OPENAI_API_KEY for the default model in the TelegramTools example
• 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:

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 for more usage patterns including streaming, teams, workflows, and multiple instances.

Parameters

Provide agent, team, or workflow. Call get_router() to get the FastAPI APIRouter with all endpoints attached.

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"}, {"status": "ignored"}, or {"status": "duplicate"}; 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, or workflow, the /new command creates a fresh session. Without a database, /new has no persisted session to replace. History and memory are not persisted.

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, such as OpenAITools with GPT Image 2 or ElevenLabsTools. 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.

from agno.agent import Agent
from agno.tools.telegram import TelegramTools

agent = Agent(
    tools=[TelegramTools(chat_id="123456789", all=True)],
)

Toolkit Parameters

Toolkit Methods

Message-sending methods return a JSON string with {"status": "success", "message_id": ...} on success or {"status": "error", "message": ...} on failure. delete_message returns {"status": "success", "deleted": true}. Chat and file retrieval return their own data fields; pinning returns the pinned state and message ID.

For the full toolkit reference, see TelegramTools.

Testing the Integration

1. Run the app locally: python <my-app>.py (ensure ngrok is running)

2. Register the webhook with the same secret configured on the server:

   curl -X POST "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook" \
     --data-urlencode "url=${NGROK_URL}/telegram/webhook" \
     --data-urlencode "secret_token=${TELEGRAM_WEBHOOK_SECRET_TOKEN}"

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

Developer Resources

• Telegram setup guide
• Telegram examples
• TelegramTools reference
• Deployment templates