Skip to main content
Use the Telegram interface to serve Agents as Telegram bots. It supports text, photos, documents, voice, video, stickers, location, polls, and inline keyboard callbacks.

​
Prerequisites

Create a virtual environment and install the required dependencies: 
uv venv
source .venv/bin/activate

uv pip install upsonic fastapi uvicorn
# pip install upsonic fastapi uvicorn

​
Step 1: Create a Telegram Bot

  1. Open Telegram and search for @BotFather
  2. Send /newbot and follow the prompts to choose a name and username
  3. Copy the Bot API Token you receive — you’ll need it in the next step

​
Step 2: Set Up the Webhook with ngrok

Telegram delivers messages to your bot via webhooks — it sends HTTPS requests to a public URL you provide. Your local localhost:8000 is not accessible from the internet, so you need a tunnel. We’ll use ngrok for this.
1

Create an ngrok account

Go to ngrok.com/signup and create a free account.
2

Install ngrok

After signing up, follow the instructions on your ngrok dashboard to install ngrok for your operating system.
brew install ngrok
3

Connect your account

Copy your authtoken from the ngrok dashboard and run:
ngrok config add-authtoken YOUR_AUTH_TOKEN
4

Start the tunnel

Open a terminal and run:
ngrok http 8000
You’ll see output like this:
Forwarding  https://abc123.ngrok-free.app -> http://localhost:8000
Copy the https://....ngrok-free.app URL — this is your public webhook URL.
Keep this terminal open — if you close ngrok, the tunnel stops and your bot won’t receive messages. When you restart ngrok, the URL changes and you’ll need to update your .env file.

​
Step 3: Configure Environment Variables

Create a .env file with your credentials: 
TELEGRAM_BOT_TOKEN=your-bot-token-from-botfather
TELEGRAM_WEBHOOK_URL=https://abc123.ngrok-free.app
TELEGRAM_WEBHOOK_URL is the ngrok URL you copied. When you restart ngrok, this URL changes — update it accordingly.
You can also set an optional secret for webhook validation: 
TELEGRAM_WEBHOOK_SECRET=my-secret-token

​
Step 4: Write Your Bot

There are two operating modes — pick the one that fits your use case:
  • CHAT — The agent remembers conversation context per user. Best for conversational assistants.
  • TASK — Each message is processed independently with no history. Best for one-off queries.
import os
from upsonic import Agent
from upsonic.interfaces import InterfaceManager, TelegramInterface, InterfaceMode

agent = Agent(
    model="openai/gpt-4o-mini",
    name="TelegramChatBot",
    system_prompt="You are a friendly AI assistant on Telegram. You remember conversation context.",
)

telegram = TelegramInterface(
    agent=agent,
    bot_token=os.getenv("TELEGRAM_BOT_TOKEN"),
    webhook_url=os.getenv("TELEGRAM_WEBHOOK_URL"),
    webhook_secret=os.getenv("TELEGRAM_WEBHOOK_SECRET"),
    mode=InterfaceMode.CHAT,
    reset_command="/reset",
)

manager = InterfaceManager(interfaces=[telegram])
manager.serve(host="0.0.0.0", port=8000)

​
Step 5: Run

Make sure ngrok is running in one terminal, then start your bot in another: 
uv run your_bot.py
# python your_bot.py
Your bot is now live. Open Telegram, find your bot by username, and send a message.

​
Operating Modes

ModeDescriptionBest For
TASK (default)Each message is processed independently. No conversation history.One-off queries, stateless bots
CHATMessages from the same user share a session. The agent remembers context.Conversational assistants, support bots

​
Reset Command (CHAT mode only)

In CHAT mode, users can clear their conversation by sending /reset. Configure it with reset_command; set to None to disable. If the agent has a workspace configured, the reset command will also trigger a dynamic greeting message based on the workspace configuration.

​
Access Control

Restrict your bot to specific users by passing a list of Telegram user IDs: 
telegram = TelegramInterface(
    agent=agent,
    bot_token=os.getenv("TELEGRAM_BOT_TOKEN"),
    webhook_url=os.getenv("TELEGRAM_WEBHOOK_URL"),
    mode=InterfaceMode.CHAT,
    allowed_user_ids=[1279809673],
)
Users not in the list are ignored. Omit allowed_user_ids (or set None) to allow everyone.

​
Supported File & Message Types

Users can send any file type through Telegram — images, PDFs, Excel spreadsheets, Word documents, CSVs, and more. The bot receives and forwards all of them to your agent.
  • Images (PNG, JPG, etc.) – The agent can process these directly via its vision capabilities
  • PDFs, Excel, Word, CSV, and other documents – The agent receives the file. If you equip your agent with the right tools (e.g. a PDF reader tool or an Excel parser), it can read and analyze the contents
  • Voice / Audio – Downloaded and processed (e.g. transcription)
  • Video / Video note – Downloaded and processed with caption
  • Text – Processed as task or chat input
  • Sticker – Converted to text (e.g. “User sent a sticker: ”)
  • Location / Venue / Contact / Poll – Converted to text and processed
  • Callback query – Inline keyboard button data processed as text
Your agent can already handle images natively. For other file types like PDF or Excel, add a custom tool to your agent so it can read and process them. See Custom Tools for how to create one.