Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt

Use this file to discover all available pages before exploring further.

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="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)

​
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 Creating function tools for how to create one.