> ## 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 Bot

> Deploy agents on Telegram for direct and group chat interactions.

This example creates a simple agent for answering questions on Telegram:

```python theme={null}
from agno.agent import Agent
from agno.models.google import Gemini
from agno.os.app import AgentOS
from agno.os.interfaces.telegram import Telegram

telegram_agent = Agent(
    name="Telegram Bot",
    model=Gemini(id="gemini-2.5-pro"), # Ensure GOOGLE_API_KEY is set
    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="telegram_bot:app", port=7777, reload=True)
```

<Note>
  Install the dependency: `uv pip install 'agno[telegram]'`
</Note>

<Note>
  Each Telegram chat gets its own session scope (e.g., `tg:Telegram Bot:123456789`), so conversations stay isolated across chats.
</Note>

## Built-in Commands

The Telegram interface registers three commands automatically:

| Command  | Default Behavior                                  | Customization Parameter |
| -------- | ------------------------------------------------- | ----------------------- |
| `/start` | Sends a welcome message                           | `start_message`         |
| `/help`  | Lists supported input types                       | `help_message`          |
| `/new`   | Starts a fresh conversation (requires a database) | `new_message`           |

Commands are registered with the Telegram Bot API on first message when `register_commands=True` (default).

## Key Features

| Feature          | Details                                                                                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Streaming        | Edits the response message in real time as tokens arrive. Throttled to \~1 edit/sec for rate limits. Enable with `streaming=True` (default).      |
| Media input      | Accepts photos, voice notes, audio, video, video notes, stickers, GIFs, and documents. Media is downloaded and passed to the agent automatically. |
| Media output     | Agent tools (e.g., DALL-E, ElevenLabs) can send photos, audio, video, documents, GIFs, and stickers as native Telegram media.                     |
| Message chunking | Responses longer than 4096 characters are automatically split across multiple messages.                                                           |
| Show reasoning   | Set `show_reasoning=True` to surface the model's reasoning as a blockquote message.                                                               |

## Local Development Setup

<Steps>
  <Step title="Prerequisites">
    Ensure you have the following:

    * A Telegram account
    * ngrok (for development)
    * Python 3.7+
  </Step>

  <Step title="Create a Telegram Bot">
    1. Open Telegram and message [@BotFather](https://t.me/BotFather)
    2. Send `/newbot` and follow the prompts to choose a display name and username (username must end in `bot`, e.g. `my_agno_bot`)
    3. Copy the bot token (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`)
  </Step>

  <Step title="Set Environment Variables">
    ```bash theme={null}
    export TELEGRAM_TOKEN="your-bot-token-from-botfather"
    export APP_ENV="development"  # Bypasses webhook secret validation for local testing
    ```
  </Step>

  <Step title="Start a Tunnel with ngrok">
    Telegram needs a public HTTPS URL to deliver webhook events:

    ```bash theme={null}
    ngrok http 7777
    # Or, if you have a paid ngrok plan with a static domain:
    # ngrok http --domain=your-custom-domain.ngrok-free.app 7777
    ```

    Copy the `https://` forwarding URL provided by ngrok and set it as an environment variable:

    ```bash theme={null}
    export NGROK_URL=https://your-subdomain.ngrok-free.app
    ```
  </Step>

  <Step title="Run the App">
    ```bash theme={null}
    python telegram_bot.py
    ```

    The server starts on `http://localhost:7777`.
  </Step>

  <Step title="Register the Webhook">
    Tell Telegram to send updates to your tunnel URL:

    ```bash theme={null}
    curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=${NGROK_URL}/telegram/webhook"
    ```

    You should see `{"ok":true,"result":true,"description":"Webhook was set"}`.

    Verify anytime with:

    ```bash theme={null}
    curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/getWebhookInfo"
    ```
  </Step>
</Steps>

## Production Deployment

In production, webhook secret validation is enforced. Telegram sends the secret in the `X-Telegram-Bot-Api-Secret-Token` header, and the interface rejects requests with an invalid or missing token with a `403`.

<Steps>
  <Step title="Set the Webhook Secret">
    Generate a secret and set it as an environment variable:

    ```bash theme={null}
    export TELEGRAM_WEBHOOK_SECRET_TOKEN="your-random-secret-string"
    ```
  </Step>

  <Step title="Register the Webhook with the Secret">
    Pass the `secret_token` parameter when registering your webhook:

    ```bash theme={null}
    curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=https://your-domain.com/telegram/webhook&secret_token=${TELEGRAM_WEBHOOK_SECRET_TOKEN}"
    ```
  </Step>

  <Step title="Remove APP_ENV=development">
    Do **not** set `APP_ENV=development` in production. Without it, webhook secret validation is active.
  </Step>
</Steps>

## Group Chat Setup

By default, Telegram bots in groups only receive commands (`/start`, etc.), @mentions, and replies to their own messages. To allow the bot to read all group messages:

<Steps>
  <Step title="Disable Privacy Mode in BotFather">
    1. Open a chat with [@BotFather](https://t.me/BotFather)
    2. Send `/mybots` and select your bot
    3. Go to **Bot Settings** → **Group Privacy**
    4. Tap **Turn off**

    BotFather confirms: *"Privacy mode is disabled for YourBot."*
  </Step>

  <Step title="Re-add the Bot to Existing Groups">
    Privacy mode changes only apply to groups the bot joins **after** the change. Remove and re-add the bot to any existing groups. Alternatively, making the bot a group admin bypasses privacy mode entirely.
  </Step>

  <Step title="Configure Reply Behavior">
    Control whether the bot responds to every message or only mentions:

    ```python theme={null}
    Telegram(
        agent=telegram_agent,
        reply_to_mentions_only=True,   # True (default): respond to @mentions and direct replies only
        reply_to_bot_messages=True,    # True (default): also respond when users reply to the bot's messages
    )
    ```

    Set `reply_to_mentions_only=False` to respond to all messages in the group.
  </Step>
</Steps>

## Troubleshooting

| Problem                       | Cause                                        | Fix                                                                                                                                         |
| ----------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `403 Forbidden` on webhook    | Missing or invalid webhook secret            | Set `TELEGRAM_WEBHOOK_SECRET_TOKEN` and register the webhook with a matching `secret_token`, or set `APP_ENV=development` for local testing |
| Bot doesn't respond in groups | Privacy mode enabled                         | Disable privacy mode in BotFather and re-add the bot to the group                                                                           |
| Bot doesn't respond at all    | Webhook not registered or server not running | Verify with `getWebhookInfo` and check that your server is reachable                                                                        |
| Streaming not working         | `streaming` set to `False`                   | Set `streaming=True` on the `Telegram` interface (this is the default)                                                                      |

## Developer Resources

* [Telegram Interface](/agent-os/interfaces/telegram/introduction)
* [Deployment Templates](/deploy/templates)
* [Discord](https://agno.link/discord)