Telegram

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

Open Telegram and search for @BotFather
Send /newbot and follow the prompts to choose a name and username
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.

Create an ngrok account

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

Install ngrok

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

brew install ngrok

snap install ngrok

choco install ngrok

Connect your account

Copy your authtoken from the ngrok dashboard and run:

ngrok config add-authtoken YOUR_AUTH_TOKEN

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="anthropic/claude-sonnet-4-6",
    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)

import os
from upsonic import Agent
from upsonic.interfaces import InterfaceManager, TelegramInterface, InterfaceMode

agent = Agent(
    model="anthropic/claude-sonnet-4-6",
    name="TelegramBot",
    system_prompt="You are a helpful AI assistant on Telegram. Be concise.",
)

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.TASK,
)

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

Mode	Description	Best For
TASK (default)	Each message is processed independently. No conversation history.	One-off queries, stateless bots
CHAT	Messages 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 Creating function tools for how to create one.

GET STARTED

CONCEPTS

STARTING AN AGENT PROJECT

READY TO USE SNIPPETS

DEPLOYMENT

FURTHER READINGS

Prerequisites

Step 1: Create a Telegram Bot

Step 2: Set Up the Webhook with ngrok

Step 3: Configure Environment Variables

Step 4: Write Your Bot

Step 5: Run

Operating Modes

Reset Command (CHAT mode only)

Access Control

Supported File & Message Types

​Prerequisites

​Step 1: Create a Telegram Bot

​Step 2: Set Up the Webhook with ngrok

​Step 3: Configure Environment Variables

​Step 4: Write Your Bot

​Step 5: Run

​Operating Modes

​Reset Command (CHAT mode only)

​Access Control

​Supported File & Message Types

Prerequisites

Step 1: Create a Telegram Bot

Step 2: Set Up the Webhook with ngrok

Step 3: Configure Environment Variables

Step 4: Write Your Bot

Step 5: Run

Operating Modes

Reset Command (CHAT mode only)

Access Control

Supported File & Message Types