Skip to main content
Agno and AgentOS make it easy to deploy your agents on Telegram with just 2 extra lines of code. This example creates a simple agent for answering questions: 
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.os import AgentOS
from agno.os.interfaces.telegram import Telegram

telegram_agent = Agent(
    name="Telegram Bot",
    model=OpenAIChat(id="gpt-4o-mini"),
    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 Telegram dependency: pip install 'agno[telegram]'
In DMs, each chat gets its own session. In group chats, sessions are scoped by reply thread so each conversation maintains its own context.

​
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 search for @BotFather
  2. Send /newbot
  3. Follow the prompts to choose a name and username for your bot
  4. BotFather will respond with your bot token (looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
  5. Save this token securely
3

Setup Environment Variables

Create a .env file in your project root:
TELEGRAM_TOKEN="your-bot-token-from-botfather"
For development, also set:
APP_ENV="development"
This bypasses webhook secret validation for local testing.
4

Setup Webhook with ngrok

  1. Run ngrok to expose your local server: 
    ngrok http 7777
  2. Copy the https:// URL provided by ngrok
  3. Set the webhook by running: 
    curl "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://<YOUR_NGROK_URL>/telegram/webhook"
  4. Verify the webhook is set: 
    curl "https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo"
5

Configure for Production

For production deployments, set a webhook secret for request validation:
TELEGRAM_WEBHOOK_SECRET="your-random-secret-string"
APP_ENV="production"
Set the webhook with the secret token:
curl "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://<YOUR_DOMAIN>/telegram/webhook&secret_token=<YOUR_SECRET>"
6

Configure Bot Settings (Optional)

Use BotFather to customize your bot:
  • /setdescription - Set the bot’s description
  • /setabouttext - Set the “About” text
  • /setuserpic - Set the bot’s profile picture
  • /setcommands - Set the command menu (e.g., /start, /help)
To allow the bot to read all messages in groups (not just @mentions):
  1. Send /mybots to BotFather
  2. Select your bot
  3. Go to “Bot Settings” > “Group Privacy”
  4. Disable privacy mode
ngrok is used only for local development and testing. For production deployments, see the deployment tutorials.

​
Developer Resources