Install the Telegram dependencies: uv pip install 'agno[telegram]'
Local Development
Prerequisites
Ensure you have the following:
- A Telegram account
- ngrok (for development)
- Python 3.9+
Create a Telegram Bot
- Open Telegram and message @BotFather
- Send
/newbot and follow the prompts to choose a display name and username (username must end in bot, e.g. my_agno_bot)
- Copy the bot token (looks like
123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)
Set Environment Variables
export TELEGRAM_TOKEN="your-bot-token-from-botfather"
export APP_ENV="development" # Bypasses webhook secret validation for local testing
Start a Tunnel with ngrok
Telegram needs a public HTTPS URL to deliver webhook events:Copy the https:// forwarding URL provided by ngrok and set it as an environment variable:export NGROK_URL=https://your-subdomain.ngrok-free.app
Run the App
The server starts on http://localhost:7777. Register the Webhook
Tell Telegram to send updates to your tunnel URL:curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=${NGROK_URL}/telegram/webhook"
{"ok":true,"result":true,"description":"Webhook was set"}.Verify anytime with: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.
Set the Webhook Secret
Generate a secret and set it as an environment variable:export TELEGRAM_WEBHOOK_SECRET_TOKEN="your-random-secret-string"
Register the Webhook with the Secret
Pass the secret_token parameter when registering your webhook:curl "https://api.telegram.org/bot${TELEGRAM_TOKEN}/setWebhook?url=https://your-domain.com/telegram/webhook&secret_token=${TELEGRAM_WEBHOOK_SECRET_TOKEN}"
Remove APP_ENV=development
Do not set APP_ENV=development in production. Without it, webhook secret validation is active.
