Skip to main content
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
  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

4

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:
5

Run the App

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

Register the Webhook

Tell Telegram to send updates to your tunnel URL:
You should see {"ok":true,"result":true,"description":"Webhook was set"}.Verify anytime with:

​
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:
2

Register the Webhook with the Secret

Pass the secret_token parameter when registering your webhook:
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.