Telegram
Telegram needs no public address, no app review, and no workspace admin. A BotFather token is the whole credential, which makes it the fastest channel to get running.
What you need
- Message @BotFather, send
/newbot, and copy the token it gives you. - Decide whether the bot reads every group message or only the ones addressed to it. BotFather's
/setprivacycontrols this. With privacy mode on (Telegram's default) a group message reaches the bot only when it mentions the bot or replies to it. Turn it off if you want a Route that answers everything in a group. - Add the bot to the group or forum you want it in. In a forum, add it to the topics it should watch.
Write the token to a file — it never goes in a command line:
umask 077 && printf '%s' '123456:ABC-…' > /tmp/telegram-token
The file may also be JSON with a botToken key.
Add it to Hub
clisbot channels add telegram --account main --secret-file /tmp/telegram-token
rm /tmp/telegram-token
Hub probes the token with getMe before storing it, encrypts it into a Connection, and starts the account. clisbot channels ls shows the transport state.
In the app: Channels → Connections → Add Route, choose Connect a new one, pick Telegram, paste the token into the credential form, then finish the Route.
Polling is the default and needs nothing else. The webhook transport needs a public HTTPS URL and a secret token, and Hub refuses to compile it until you supply both.
Conversations it handles
Direct messages, basic groups, supergroups, and forum topics. A forum topic is addressed by its thread id, and a Route can target one topic without touching the rest of the forum. A reply lands in the same topic it came from.
Inbound covers messages, /commands (including /command@yourbot in a group), button and select callbacks, message edits, reactions, poll answers, member joins and leaves, topic events, and media groups. Photos, documents, voice, video, video notes, and location arrive as attachments within the account's size cap.
What the agent can do
Message tool actions: send, poll, react, edit, delete, sticker, sticker-search, topic-create, topic-edit.
Replies are written in markdown and rendered before they are posted. By default the account posts native rich blocks: headings stay headings, lists and blockquotes stay lists and blockquotes, fenced code keeps its language, and a markdown table becomes a real Telegram table. Charts have no Telegram primitive and always degrade to text. Long answers split into ordered chunks.
A send can also carry a structured presentation — tables, charts, buttons and selects in the portable block vocabulary. On the default account a table posts as a native Telegram table block and the buttons become an inline keyboard; a chart posts as text. Set richMessages: false and the table degrades to text with the rest of the message.
Set richMessages: false on the account to post Bot API HTML instead: bold, italic, links, blockquotes, inline code and fenced code become Telegram entities, bullet lists become • lines, and a markdown table becomes a column-aligned code block. Headings flatten to plain text — Telegram HTML has no heading tag.
Buttons and select menus are inline keyboards; an approval prompt is an inline keyboard whose press comes back as a callback.
Limits
- No group DMs — Telegram has no such conversation.
- Inside a forum topic the agent can only
edit,reactto ordeletea message the bot itself observed there: the message it is answering, a message it received in that topic, or one it sent there. A message id it did not observe is refused, and the refusal says so. - Sticker vision is unavailable: the agent is told a sticker arrived, not what it depicts.
- The webhook transport is wired but has never run against a public URL.
- Bot API rate limits apply per chat; sends are throttled rather than dropped.
Verified live
| Capability | Evidence |
|---|---|
| Mention → agent reply | Verified 2026-09-07. |
| Long formatted reply in a forum topic | Verified 2026-09-07 — seven chunks, all in the right topic. |
| Inbound files | Verified 2026-09-07 — agent read the document body back. |
| Outbound files | Verified 2026-09-07 — document and photo. |
| Message tool actions | Verified 2026-09-07 for send, edit, and poll; send and poll re-verified 2026-09-08 in a forum topic. |
edit and react inside a forum topic | Verified 2026-09-08 — the bot edited its own reply in a topic and reacted to the message it was answering, read back off the platform. |
Structured presentation (tables) | Verified 2026-09-08 — a 3x3 table asked for through the message tool posted as a native table block, read back off the platform. |
| Markdown rendering | Verified 2026-09-07 — headings, bold, italic, link, list, blockquote, inline and fenced code, and a native table, read back off the platform. |
Native rich blocks (richMessages) | Verified 2026-09-07 — the default; heading, paragraph, list, blockquote, pre and table blocks accepted by the Bot API. |
/new and /stop | Verified 2026-09-07. |
/help | Not delivered on the 2026-09-07 run. |
| Streaming, restart durability, approval prompts | Not verified. |
The running record with message ids is docs/tests/channels/p0-live-scenarios.md in the repository.
Troubleshooting
The bot ignores group messages. Privacy mode is on and the message did not address it. Either mention the bot or turn privacy off with /setprivacy.
A reply lands in the wrong place in a forum. A basic group silently drops the topic id — the Bot API answers ok: true and posts at the group root. Check that the group really is a forum before blaming the Route.
Unauthorized in the account detail. The token was revoked or regenerated in BotFather. Add the account again with the new token.
A quiet chat goes silent for minutes. Older builds escalated the poll backoff after an idle long-poll timeout. Check clisbot channels status; a healthy account reports started and the poll loop resets on every completed poll, empty batches included.