Overview
rousseau telegram runs a Telegram Bot API long-poller. The daemon repeatedly calls getUpdates, routes each incoming private message through the agent, and replies via sendMessage. No public HTTP surface is exposed — long polling is a purely outbound HTTPS connection.
Source: internal/cli/telegram.go. Transport: internal/transport/telegram/.
Synopsis
rousseau telegram [--token <bot-token>] [--allow <chat-id>...] [--config <path>]
Flags
| Flag | Type | Default | Effect |
|---|---|---|---|
--token |
string | telegram.token |
Bot token from @BotFather. |
--allow |
[]string | telegram.allowlist |
Restrict inbound to these chat ids. Repeatable. |
--config |
string | inherits from root | Path to the YAML config file. |
Config keys respected
internal/config/config.go TelegramConfig:
| Key | Type | Default | Effect |
|---|---|---|---|
telegram.token |
string | empty | Bot token. |
telegram.base_url |
string | https://api.telegram.org |
Override Bot API endpoint (self-hosted telegram-bot-api or proxy). |
telegram.reply_header |
string | empty | Prefix prepended to outbound messages. |
telegram.allowlist |
[]string | empty | Chat ids permitted. Strings. |
Allowlist syntax
Telegram chat ids are integers as returned by chat.id in Bot API updates. Rousseau treats them as strings for allowlist matching:
telegram:
allowlist:
- "123456789" # positive integer for private chats
telegram:
allowlist:
- "-987654321" # negative integer for groups
telegram:
allowlist:
- "-1001234567890" # -100... prefix for channels/supergroups
To discover a chat id, message the bot once with an empty allowlist and grep the logs for the router.transport.received event; the sender attribute is the id.
Environment variables
| Variable | Effect |
|---|---|
ROUSSEAU_TELEGRAM_TOKEN |
Overrides telegram.token. |
ROUSSEAU_TELEGRAM_BASE_URL |
Overrides the Bot API endpoint. |
Startup sequence
- Resolve token from flag, env, or config; fail if empty.
- Default
claudecli.permission_modetobypassPermissions. - Open session store, build provider, tool registry, approver, compressor.
telegram.New— instantiate the Bot API client.wiring.startCron— cron deliveries land viasendMessage.- Long-poll loop until context cancelled.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Clean context cancellation. |
| 1 | Missing token, HTTP transport error, provider/store failure. |
| 130 | SIGINT. |
Worked examples
# Ad-hoc single-user bot
rousseau telegram --token 7000000000:AAE… --allow 123456789
# From config, no flags
cat > ~/.config/rousseau/config.yaml <<'EOF'
telegram:
token: "7000000000:AAE…"
allowlist:
- "123456789"
- "-987654321"
EOF
rousseau telegram
Common failure modes
Unauthorized— invalid or revoked bot token. Regenerate with @BotFather.Conflict: terminated by other getUpdates request— two rousseau instances polling the same token. Only one Bot API long-poll at a time.Forbidden: bot was blocked by the user— user blocked the bot; outbound messages to that chat fail permanently.- Silent inbound drops — the sender's chat id is not on the allowlist. Check
router.transport.rejected.