Telegram

Each agent can be wired to a dedicated Telegram bot. When bound, the agent receives inbound messages as jobs and sends replies back to the same chat.

The binding is per-agent and per-bot: one bot token, one agent. You can have multiple agents each with their own bot.

You configure it in the dashboard, on the agent's Channels tab — the same place as Discord, Slack and WhatsApp.

Prerequisites

• A Telegram bot token. Create one with @BotFather on Telegram (/newbot).

Set up the bot

1. Open the agent's edit page in the dashboard → Channels tab → Telegram card.
2. Paste the bot token into the Bot token field → Connect.
3. The runner picks up the new token within 30 seconds and starts long-polling for updates automatically. No restart needed.

That's it — send a message to the bot and the agent responds.

How incoming messages become jobs

The runner maintains one long-polling loop per configured bot. Each incoming Telegram update is turned into an agent_jobs row inside a database transaction that also advances the offset cursor. A crash mid-update does not drop the message or create a duplicate job.

In private chats every message from an authorized chat triggers a job (see Who can talk to your bot — the first DM requests ownership, which you approve in the dashboard; unknown chats are held for the owner's approval).

In group chats the bot only responds when clearly addressed:

• /ask <agent-slug> <text> — routes to a different agent in the same workspace
• /agents or /start — reserved commands
• @bot_username <text> — mention with the bot's username
• A reply to a previous bot message

Any other group message is silently ignored, so the bot does not respond to every line of a group conversation.

Delivery guard — no phantom sends

telegram_send_message is only available to a job that has a resolvable recipient: a job that arrived via Telegram (carrying the sender's chat ID), a cron automation with "notify on success" enabled and a known chat, or a dashboard task sent "via Telegram."

On a plain dashboard, API, or internal job there is no chat recipient, so the tool is not offered at all. This prevents the agent from attempting a Telegram send on a job that has nowhere to deliver — which would otherwise produce a telegram_no_recipient error and cause the job to fail.

Approval heads-up on Telegram

When a job is paused waiting for your approval of a tool call, the agent gets up to a bounded number of turns to tell you — in its own voice, via telegram_send_message — what it launched and that it is waiting. Once it has delivered that message (or the budget is spent), the job suspends. You resolve the approval from the dashboard; the job then resumes and executes the approved action.

Who can talk to your bot

A Telegram bot's username is public, so anyone who finds it could message it. To keep strangers from putting your agent to work, each bot has an allowlist:

• You claim it by DMing it, then confirming in the dashboard. The first private message to a freshly connected bot records an owner claim — it does not grant anything yet, and no job runs. Open Agents → your agent → Channels, approve that conversation, and it becomes the bot's owner. From then on your messages go straight through.

  The extra click is the point. A bot's username is public and searchable, and the claim used to be granted to whoever messaged first — so between the moment you pasted the token and the moment you sent your DM, a stranger who had found the bot could take your place, task your agent, and receive its approval cards. Now the first claimant only ever gets a request you can refuse.

• A new person is held for your approval. If someone the bot doesn't know messages it, no job runs. Instead you (the owner) get a card in your own chat — "👤 Name wants to talk to this bot. Allow?" — with ✅ Autoriser / ❌ Refuser buttons. Only you can decide. Allow them once and their future messages go through; refuse and they stay blocked. The person is told their request is pending, so nobody is left wondering.

Groups work the same way: the bot only acts in a group once you've approved that group. You must DM the bot to claim ownership before any group can be approved.

Group chat tip

If you want to address a specific agent in a group, use:

/ask <agent-slug> your question here

This routes the message to the named agent even if the group's bot belongs to a different one.

Related

• Skill reference: Telegram responder — replying on a messaging channel, loaded on demand
• Concepts: Agents
• Concepts: Connectors & MCP