Skip to main content
This example creates a simple agent for answering questions on Telegram: 
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)
Install the dependency: uv pip install 'agno[telegram]'
Each Telegram chat gets its own session scope (e.g., tg:Telegram Bot:123456789), so conversations stay isolated across chats.

​
Setup and Configuration

1

Prerequisites

Ensure you have the following:
  • A Telegram account
  • ngrok (for development)
  • Python 3.7+
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
# 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:
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"
ngrok is used only for local development and testing. For production deployments, see the deployment tutorials.

​
Developer Resources