agent-relay-telegram

Telegram bridge daemon for Agent Relay. It lets Telegram users message an Agent Relay target, and lets relay agents reply, react, edit messages, and send files back to Telegram.

The bridge is a standalone Bun process. It does not use MCP stdio in the critical path: grammY long-polls Telegram, while a separate loop polls Agent Relay.

This is the first Agent Relay Connector and channel implementation:

Agents do work. Providers host agents. Integrations create work. Channels carry conversations.

Telegram is a channel connector because it opens Agent Relay to an external conversation surface. It is not an AI provider like Codex or Claude, and it is not an event connector like CI or monitoring. It carries conversations between Telegram users and relay agents.

Status

Early public package. The core bridge, pairing flow, attachments, access control, and systemd lifecycle are implemented. Expect the CLI surface to stay small and operationally focused.

Requirements

• Linux with user systemd for the built-in service installer
• Bun 1.0 or newer
• A running Agent Relay server
• A Telegram bot token from BotFather

Install

Published package:

bun install -g agent-relay-telegram
agent-relay-telegram install --no-start

From source:

git clone https://github.com/edimuj/agent-relay-telegram.git
cd agent-relay-telegram
bun install
bun run src/index.ts install --no-start

The installer writes a managed command shim to ~/.local/bin/agent-relay-telegram, so follow-up commands use the same CLI name whether you installed from npm or from a source checkout. If agent-relay-telegram doctor warns that ~/.local/bin is not on PATH, add it to your shell profile.

Edit the generated env file:

$EDITOR ~/.agent-relay/extensions/agent-relay-telegram/.env

Minimum configuration:

TELEGRAM_BOT_TOKEN=123456:bot-token-from-botfather
AGENT_RELAY_URL=http://localhost:4850
RELAY_DELIVER_TO=macmini2-telegram-telegram-9777ee

Start the service:

systemctl --user enable --now agent-relay-telegram.service

Check local setup:

agent-relay-telegram doctor

The installer also registers the connector manifest at ~/.agent-relay/connectors/telegram/manifest.json, which lets the Agent Relay dashboard discover and manage it. The manifest can be inspected directly:

agent-relay-telegram manifest --json
agent-relay-telegram status --json
agent-relay-telegram doctor --json

Pair First User

Open the Telegram bot and send /start. The bot replies with a pairing code:

agent-relay-telegram pair abc123

Run that command on the machine hosting the bridge. After pairing, messages from that Telegram user are forwarded to Agent Relay.

Useful Telegram commands:

• /start pairs the chat or shows chat/user IDs
• /status shows access state, relay target, and file limits
• /help shows bridge commands and behavior

Configuration

All configuration is environment-based. The daemon reads .env from TELEGRAM_STATE_DIR.

| Variable | Default | Purpose | | --- | --- | --- | | TELEGRAM_BOT_TOKEN | required | Telegram bot token | | AGENT_RELAY_URL | http://localhost:4850 | Relay server URL | | AGENT_RELAY_TOKEN | empty | Optional scoped Agent Relay token | | RELAY_DELIVER_TO | required | Concrete Agent Relay agent id for inbound Telegram messages. Legacy label:, tag:, and cap: values are only accepted when they resolve to exactly one ready agent, then stored as an explicit binding. | | TELEGRAM_ACCOUNT_ID | default | Stable account id for this Telegram bot | | TELEGRAM_STATE_DIR | ~/.agent-relay/extensions/agent-relay-telegram | State, access config, PID, and inbox root | | RELAY_POLL_INTERVAL | 2000 | Milliseconds between Agent Relay polls | | INBOX_PRUNE_DAYS | 7 | Delete downloaded attachments older than this | | TELEGRAM_MAX_ATTACHMENT_BYTES | 26214400 | Reject larger Telegram downloads | | INBOX_MAX_BYTES | 524288000 | Oldest-first inbox cleanup cap |

Access Control

Private chats default to pairing mode. Unknown users receive a pairing code, capped and expiring after one hour.

agent-relay-telegram access list
agent-relay-telegram access add <user_id>
agent-relay-telegram access remove <user_id>
agent-relay-telegram access policy <pairing|allowlist|disabled>
agent-relay-telegram access validate

Group chats must be configured explicitly:

agent-relay-telegram access group list
agent-relay-telegram access group add <chat_id> --require-mention
agent-relay-telegram access group mention <chat_id> <on|off>
agent-relay-telegram access group allow <chat_id> add <user_id>
agent-relay-telegram access group allow <chat_id> remove <user_id>
agent-relay-telegram access group remove <chat_id>

Use /status in Telegram to get the current chat ID and user ID.

Outbound Actions

Agents reply by sending JSON relay messages to the bridge channel agent ID, usually telegram:default.

Reply:

{
  "action": "reply",
  "chat_id": "123456",
  "reply_to": "42",
  "text": "Done.",
  "format": "text"
}

reply_to preserves Agent Relay context, but Telegram messages are sent standalone by default so the chat does not show quoted reply cards. Set replyToMode in access.json to "first" or "all" if you want native Telegram reply references.

React:

{
  "action": "react",
  "chat_id": "123456",
  "message_id": "42",
  "emoji": "👍"
}

Edit:

{
  "action": "edit",
  "chat_id": "123456",
  "message_id": "43",
  "text": "Updated text",
  "format": "markdownv2"
}

Send files with a reply:

{
  "action": "reply",
  "chat_id": "123456",
  "text": "See attached.",
  "files": ["/path/to/report.pdf"]
}

The bridge refuses to send internal state files from TELEGRAM_STATE_DIR, except downloaded inbox attachments.

Service Lifecycle

Install or refresh the user service:

agent-relay-telegram install
agent-relay-telegram update --restart

Uninstall keeps state by default:

agent-relay-telegram uninstall

Remove service and state only when you really want a clean wipe:

agent-relay-telegram uninstall --purge-state

Preview lifecycle actions:

agent-relay-telegram install --dry-run --no-start
agent-relay-telegram uninstall --dry-run
agent-relay-telegram update --dry-run --restart

Troubleshooting

Run:

agent-relay-telegram doctor
journalctl --user -u agent-relay-telegram.service -f

Common issues:

• TELEGRAM_BOT_TOKEN is required: set it in ~/.agent-relay/extensions/agent-relay-telegram/.env.
• Telegram 409 conflict: another process is polling the same bot token. Stop the duplicate process.
• Messages arrive in Telegram but not Agent Relay: verify AGENT_RELAY_URL, AGENT_RELAY_TOKEN, and RELAY_DELIVER_TO.
• Agent replies are ignored: the destination chat/user must be allowlisted or paired.
• Attachments disappear: check INBOX_PRUNE_DAYS and INBOX_MAX_BYTES.

Development

bun install
bun test
bun run typecheck
bun run pack:check

Package smoke test:

tmp="$(mktemp -d)"
bun pm pack --destination "$tmp"

Security And Privacy

The bridge stores .env, access.json, a PID file, and downloaded Telegram attachments under TELEGRAM_STATE_DIR. State files are written with private file modes where practical. Attachments are pruned by age and total inbox size.

Do not expose your Telegram bot token or Agent Relay token. Treat Telegram messages and downloaded files as private user data.

Report vulnerabilities privately by opening a GitHub security advisory or contacting the maintainer.

License

AGPL-3.0-or-later