Cast — Your agent team, on your machine

docspluginstransportstelegram

The Telegram bot API — direct messages and group chats reach an agent through a bot you mint with BotFather and connect to the server.

Getting a bot token

Telegram bot tokens are minted by BotFather, an in-app bot you message directly.

Open Telegram and start a chat with @BotFather.
Send /newbot and follow BotFather's prompts to name your bot.
BotFather replies with a token of the form 123456:ABC-DEF…. That's the credential.

Route configuration

Each Telegram entry binds one bot to one agent. Run multiple agents by adding more entries — one bot per agent.

routes.json

json · telegram slice

{
  "telegram": [
    {
      "address": "assistant",
      "token": "123456:ABC-DEF...",
      "channel": "default"
    }
  ]
}

Field	Type	Default	Effect
address	string	required	Canonical agent address this bot routes to.
token	string	required	The BotFather token. Masked in the admin form; stored in routes.json.
channel	string	—	Channel preset for conversations. Falls back to the agent's default.
streaming	boolean	true	Live edit-in-place streaming. Set false where the editing UX is unwanted or Telegram rate limits make live edits flaky — the bubble never opens and each response is sent once, sealed.

What works in chat

Live streaming — the bot posts a message and edits it in place as the agent writes, then seals it when the turn finishes.
Approvals — sensitive actions appear as inline keyboard buttons; tap approve or reject and the message updates with the decision.
DMs and groups — works one-on-one or in a group. In groups, Telegram's default privacy mode means the bot only sees messages directed at it — which suits assistant-style use, no change needed.
Attachments — inbound photos, documents, voice, audio, video, and stickers reach the agent, along with structured payloads like contacts, locations, and polls. Outbound files are sent in the right format for their type.
Typing indicator — shows while the agent is working.
Command menu — Cast keeps the bot's / menu in sync with the server's system commands automatically.

Notes & gotchas

💡 TIP

Privacy mode is on by default and needs no change for DM-style use. Cast manages the BotFather command menu (/setcommands) for you — don't set it manually.

Credentials sit in routes.json with no separate secrets file — see Transports for the config model shared across all transports.