#Telegram

Telegram needs no public address, no app review, and no workspace admin. A BotFather token is the whole credential, Use that token with Bot API polling.

#What you need

1. Message @BotFather, send /newbot, and copy the token it gives you.
2. Decide whether the bot reads every group message or only the ones addressed to it. BotFather's /setprivacy controls 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.
3. Add the bot to the group or forum. Choose the topics it should answer with the Route's Rules.

Save the token in a private file using an editor, outside your repository, and restrict it to your user (chmod 600 <token-file>). Do not put it in shell history. The file can contain the raw token or JSON with a botToken key.

#Add it to Hub

clisbot channels add telegram --account main --secret-file <token-file>

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 Connection, pick Telegram, paste the token into the credential form, then finish the Route.

Polling is the supported transport and needs no public URL. Hub refuses webhook configurations even if a URL and secret are supplied.

#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 and the 20 MB inbound download limit.

Use Channel slash commands for session controls, Project/Workspace selection and this channel's invocation forms.

#What the agent can do

Message tool actions: send, poll, react, edit, delete, sticker, sticker-search, topic-create, topic-edit, emoji-list, subject to account action settings.

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, react to or delete a 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.
• Webhook transport is unavailable in Hub; use polling.
• 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.