---
title: Telegram Bot channel (talk to your agents from Telegram)
---

# Telegram Bot channel (talk to your agents from Telegram)

## What it is

The Telegram Bot channel lets you chat with your Omniscio agents from Telegram. You create a bot with BotFather, paste its token into Omniscio, and then every message you send that bot goes to an agent session. The agent's final answer comes back in the same Telegram chat.

This is a **separate** channel from the [Telegram integration](telegram-integration.md). That one signs in as *you* (your personal account) and shows your chats in the Omniscio inbox. The bot channel never touches your account: it runs a bot, and it is only for talking to agents.

## Where to find it

You create the bot with **@BotFather** in Telegram, then turn the channel on and paste its token into Omniscio at **Settings → Channels → Telegram Bot**. The pairing request triggered by your first message appears in that same settings card (and as an inbox alert), where you click **Approve**.

## How it behaves

### What it does

- **One chat, one session.** A direct message with the bot, a group, or a forum topic inside a group each map to their own agent session. Send a follow-up and it goes to the same session. Send `/new` to start a fresh one.
- **Replies come back to the same place.** When the agent finishes a turn, its final answer is posted back into the chat (or the exact forum topic) as formatted text, split into several messages when it is long. While the agent works, the chat shows "typing…".
- **Survives restarts.** The chat-to-session links and the Telegram update position are stored in the database, so quitting and reopening Omniscio picks up where it left off without replaying old messages.
- **Uses your normal agent setup.** Sessions spawn through the same path as any other session, so whichever Claude sign-in you use (subscription passthrough, your own key, or Omniscio's managed pool) applies. The bot never reads or copies any Claude credential.

### Setting it up

1. In Telegram, open **@BotFather**, send `/newbot`, and follow the prompts. Copy the token it gives you (it looks like `123456789:AA…`).
2. In Omniscio go to **Settings → Channels → Telegram Bot**, turn the channel on, and paste the token. Omniscio checks it with Telegram before saving and shows "Connected as @yourbot".
3. Message your bot from Telegram. The first time, the bot replies with a pairing code and the request appears in the same settings card (and as an inbox alert). Click **Approve**. From then on your messages reach an agent.

To use the bot in a group: add the bot to the group, copy the group's numeric id into **Allowed groups**, make sure you are an allowed user, and @mention the bot in your message (or reply to one of its messages). Forum topics inside the group each get their own session automatically.

### Who is allowed to talk to it

This is real access control for who may drive a paid agent, and it is deliberately separate from the automations "Approved Senders" list (a cost guard for inbox-triggered automations). Bot traffic never enters the automations engine.

| Setting | What it does |
| --- | --- |
| Who can message the bot | **Pairing** (default): unknown senders get a one-time code and are not routed until you approve. **Allowed users only**: no pairing prompt. **Nobody**: DMs are ignored. |
| Allowed users | Numeric Telegram user ids. Approving a pairing request adds the sender automatically. Empty admits nobody. |
| Allowed groups | Numeric group ids the bot will answer in. Empty means the bot ignores every group. |
| Require @mention in groups | On by default. The bot only reacts to group messages that mention it or reply to it. |

Pairing codes expire after one hour, at most three can be pending at once, and every refusal is silent so a stranger who finds the bot learns nothing.

### Commands

| Command | Effect |
| --- | --- |
| `/start` | A short welcome and the command list. |
| `/new` | Detach this chat from its session; the next message opens a new one. |
| `/status` | Show which session this chat is linked to and its status. |

### Limits and safety

- Only text messages are routed. A photo, file, or voice note gets a short "text only" reply.
- Inbound text is wrapped in explicit untrusted-content markers with a security notice, so the agent treats it as the user's request and never as instructions to reveal secrets or run commands because the message said so.
- A chat can spawn at most one new session every 15 seconds, and the bot spawns at most 50 new sessions per day.
- When an agent stops for an approval that only the desktop can grant, the bot tells you so instead of leaving "typing…" running.
- If the bot token is revoked, or another program starts polling the same bot, polling stops and an inbox alert explains what to do.

### Planned follow-ups (not in this version)

- Streaming replies edited in place while the agent is still working.
- Inbound photos, documents, and voice notes handed to the session as attachments.
- Quoting the replied-to message as context.
- Inline Approve / Deny buttons for permission requests.
- Webhook transport as an alternative to long polling.
- Choosing a real project (repo) as the session host instead of the Telegram Bot workspace.
- More than one bot account.

## For agents

### Command line

Agents and scripts can read the status and manage pairing and chats through the local control server: see the [telegram-bot](../../.claude/skills/omniscio-control/telegram-bot.md) surface (`/telegram-bot/status`, `/telegram-bot/pairing`, `/telegram-bot/chats`, `/telegram-bot/allowed`). Setting the token and signing the bot out are desktop-only.

## Related

[Telegram integration](telegram-integration.md) is the other, unrelated Telegram channel: it signs in as you and shows your chats in the Omniscio inbox, where this bot channel only ever talks to agents. [Mobile remote access](mobile-remote-access.md) covers reaching your Omniscio install from a phone, which is the other way to talk to your agents while away from the desktop.