Telegram bot
Get started

Telegram bot

16. Telegram bot#

Drive a Rayu session from your phone. Send a prompt from Telegram, watch the answer stream back, approve the tools the agent wants to run, and answer its questions without walking back to your desk.

v3 pairs one private Telegram chat with the shared daemon on your machine. Whatever the chat drives is a real session on that machine, with the same tools and the same files.

Plan access: the Telegram bot is included on paid plans (Basic and up). See Subscription plans.

How it works#

  • The Rayu daemon polls Telegram. There is no separate bridge process to keep running, and no port to open.
  • A link belongs to a machine, not to a session. From the chat, /sessions attaches it to whichever session you pick.
  • Only the linked private chat is answered. Messages from every other chat, group, or bot are ignored.
  • Every tool call the agent wants to make while driven from Telegram is approved from the chat first. The chat is the approval surface in that mode, which is why it must stay private.

Pair it#

Start the daemon first by running rayu normally, then:

bash
rayu telegram link

The command prints a https://t.me/<bot>?start=<code> link, and a QR code when stdout is a terminal. Open the link on your phone and tap Start. The message it sends carries a single-use code, valid ten minutes, accepted only in a private chat. When pairing succeeds the terminal prints the bot username.

Pairing needs the shared daemon socket, so it refuses to run under a custom --socket.

Use your own bot#

If you would rather not route through the shared bot, create a bot with @BotFather and pass the token:

bash
rayu telegram link --botfather

The token is read from a masked prompt when stdin is a terminal, otherwise from stdin, so it works in a script:

bash
printf '%s' "$BOTFATHER_TOKEN" | rayu telegram link --botfather

Rayu validates the token with Telegram, registers the bot command menu, and then walks through the same pairing link. The token never leaves your machine except to Telegram's API.

If a link already exists, the command stops and tells you to disconnect first. Use --replace-existing to swap a hosted link in place.

Commands in the chat#

These are handled by the bridge itself, so they work even when no session is attached:

CommandDoes
/sessionsSession picker: a card with one button per open session (aliases /session, /switch with no argument)
/switch <n>Attach the chat to the numbered session
/statusWhich session this chat is driving, and whether the daemon is up
/modelModel picker, ten models per page, current one marked
/model <name>Set the model directly
/providerBrowse models grouped by provider
/connectReminder to run rayu login on the host. Credentials are never accepted in Telegram
/interruptCancel the current turn (alias /cancel)
/answer <text>Reply to a pending question from the agent
/stopDisconnect Telegram from this machine (aliases /disconnect, /disconnect-telegram)
/uninstallUninstall the managed CLI, when remote uninstall is enabled
/helpThe list above

Anything else that starts with / is not forwarded. The bridge answers "Unknown command" and asks you to use /help, so a stray /mcp in the chat cannot silently reconfigure a session.

Sessions#

One chat drives one session at a time. Send /sessions to see the open ones:

  • Each card shows the session name, folder, and whether it is busy, waiting, or idle.
  • The session currently attached is marked.
  • Tap a button to switch. The chat starts driving it immediately.
  • With exactly one session open, it is attached automatically.
  • The chosen session is remembered, so reopening the link does not require re-pairing.

Sessions the daemon cannot reach are listed but cannot be switched to.

Approvals from the chat#

When the agent calls a tool during a Telegram turn, the chat gets a card with Allow and Deny. The turn blocks until you answer, up to two minutes.

DetailValue
Tools that can be approvedread, glob, grep, agentgrep, bash, write, edit, apply_patch, patch, ask_user, propose_plan, send_media
Anything elseRefused outright: "This tool is unavailable on Telegram"
TimeoutTwo minutes, then the call fails and the agent sees the denial
Link lost mid-turnThe pending approval is cancelled
Stale buttonTap after the turn moved on and the chat says the request already closed

The agent also gets three interaction tools only in Telegram-driven sessions: ask_user (ask a question and wait), propose_plan (present a plan for approval), and send_media (send a PNG, JPEG, WebP, or MP4 from the project to the chat). None of them can read a password, and send_media only sends files inside the project.

Because approvals happen in the chat, the terminal is not the gate in this mode. Keep two-step verification on your Telegram account, and treat the pairing link as a password, which is what rayu telegram link calls it.

Media#

You can send photos and files into the chat and they arrive as visual or textual context for the turn. Albums are grouped and delivered together, up to ten items. The agent can send an image or short video back with send_media after you approve it.

Status and disconnection#

bash
rayu telegram status
rayu telegram disconnect
rayu telegram disconnect --local-only

status prints the bot, the link mode (Rayu account or BotFather), and whether the daemon is running. A link with no daemon is "linked but not listening": messages will not be answered.

disconnect unlinks the chat and forgets the local record. --local-only skips the server call, which is what you want when the hosted account is unreachable or you are cleaning up a half-finished pairing.

From the chat, /stop does the same thing.

Remote uninstall#

Telegram can uninstall the managed CLI, and it is off by default:

bash
rayu telegram uninstall status
rayu telegram uninstall enable
rayu telegram uninstall disable

When enabled, /uninstall in the chat requires naming the device and confirming with a code. Leave it off on a machine you care about.

Where state lives#

FilePurpose
~/.rayu/telegram-remote.jsonThe link: bot, mode, owner, generation. Written with owner-only permissions
~/.rayu/telegram-remote.cursor.jsonTelegram update offset, so restarts do not replay messages
~/.rayu/telegram-remote.poll.lockEnsures exactly one process polls Telegram

Several Rayu processes can run on one machine; the lock makes one of them the poller and the rest stay reachable through the session picker.

Troubleshooting#

SymptomTry
Messages get no replyrayu telegram status. "Daemon offline" means start rayu
Pairing link expiredCodes last ten minutes. Run rayu telegram disconnect --local-only, then rayu telegram link again
"Run rayu telegram disconnect before pairing another bot"A link already exists. Disconnect first, or use --replace-existing
"Telegram remote runs on the profile's shared daemon socket"You passed --socket. Use the default socket for pairing
Bot token rejectedBotFather tokens look like <bot-id>:<secret>. Re-copy it, and check the bot is not already linked elsewhere
Chat drives the wrong session/sessions, then tap the right one
Approvals never appearThe session may have moved on. Send /status; if it is idle, the tool already finished or expired
Group chat does not workOnly private chats can pair, by design

Next#

Next: VS Code extension →