What this gives you#
The bot runs your agent and streams replies to messages sent from your phone or desktop. History persists per chat until you run /reset. Conversations use the same session database as web and CLI interactions.
Step 1: Create a bot with BotFather#
- Open Telegram and start a chat with @BotFather
- Send
/newbotand follow the prompts (name + username) - Copy the token BotFather gives you. It looks like
123456789:ABCdef...
Step 2: Configure the token#
The fastest path is the setup wizard:
term-llm serve telegram --setupThis prompts for your token and saves it to config.yaml under serve.telegram. Re-run with --setup any time to update credentials.
To configure manually, add to ~/.config/term-llm/config.yaml:
serve:
telegram:
token: "123456789:ABCdef..."Step 3: Restrict access#
Without an allowlist, anyone who knows your bot’s username can chat with it. You almost certainly want to restrict this.
You can allowlist by numeric user ID (more stable) or by username:
serve:
telegram:
token: "123456789:ABCdef..."
allowed_user_ids:
- 987654321
allowed_usernames:
- yourusernameTo find your numeric user ID, forward a message from yourself to @userinfobot.
Messages from non-allowlisted users are silently ignored and logged.
Step 4: Start the bot#
term-llm serve telegramWith an agent and yolo mode (auto-approve tool calls):
term-llm serve telegram --agent jarvis --yoloCombined with the web UI on the same process:
term-llm serve telegram webBot commands#
| Command | What it does |
|---|---|
/start |
Show welcome message and command list |
/help |
Same as /start |
/reset |
Clear conversation history and start a fresh session |
/status |
Show message count and last activity time for the current session |
Configuration reference#
All fields live under serve.telegram in config.yaml:
| Key | Type | Default | Description |
|---|---|---|---|
token |
string | — | Bot token from BotFather. Required. |
allowed_user_ids |
list of int | — | Numeric Telegram user IDs allowed to use the bot. |
allowed_usernames |
list of string | — | Telegram usernames allowed to use the bot (without @). |
idle_timeout |
int (minutes) | — | Close idle sessions after this many minutes. |
interrupt_timeout |
int (seconds) | 3 | How long to wait for an in-flight response to stop before interrupting. |
CLI flags#
term-llm serve telegram \
--agent jarvis \
--provider anthropic \
--yolo \
--telegram-carryover-chars 4000--telegram-carryover-chars (default 4000): when a session is reset via /reset, this many characters of the previous conversation are carried into the new session as context. Set to 0 to start completely fresh on each reset.
Set default platforms in config#
If you always run the same combination, set it in config.yaml so you can just run term-llm serve:
serve:
platforms:
- telegram
- webterm-llm serve with no arguments reads from serve.platforms.
Related pages#
- Notifications: send one-off Telegram messages via
term-llm notify - Web UI and API: run the browser UI alongside the bot
- Agents: configure which agent handles bot conversations