Setup

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

Install the Telegram dependencies: uv pip install 'agno[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
   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

   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:

   ngrok http 7777
   

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

   export NGROK_URL=https://your-subdomain.ngrok-free.app
   
5. Run the App

   python telegram_bot.py
   

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

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

   You should see {"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.

1. Set the Webhook Secret

   Generate a secret and set it as an environment variable:

   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:

   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.

ngrok is for local development only. For production, see the deployment templates.