> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Create a Telegram bot with BotFather and configure webhooks for local and production deployments.

> [!NOTE]
>
> Install the Telegram dependencies: `uv pip install 'agno[os,telegram]'`

## Local Development

**1. Prerequisites**

Ensure you have the following:

* A Telegram account
* ngrok (for development)
* Python 3.9+

**2. 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`)

**3. 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
```

**4. Start a Tunnel with ngrok**

Telegram needs a public HTTPS URL to deliver webhook events:

```bash theme={null}
ngrok http 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
```

**5. Run the App**

```bash theme={null}
python telegram_bot.py
```

The server starts on `http://localhost:7777`.

**6. 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"
```

## 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`.

**1. 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"
```

**2. 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}"
```

**3. Remove APP\_ENV=development**

Do **not** set `APP_ENV=development` in production. Without it, webhook secret validation is active.

> [!WARNING]
>
> ngrok is for local development only. For production, see the [deployment templates](https://agno-v2.mintlify.site/deploy/introduction.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.