Telegram - OpenSRE Documentation

Overview

OpenSRE’s Telegram integration delivers agent messages, scheduled reports, and alarms to any chat your bot has been added to — useful for mobile-first on-call rotations and personal alerting. With the gateway running, you can also DM the agent for two-way chat. Start the interactive shell with opensre (no subcommand). Slash commands below are run from that REPL.

Prerequisites

A Telegram account.
The Telegram mobile or desktop app, signed in.
The chat (group, channel, or direct message) where you want messages delivered.

Setup

Option 1: CLI setup (recommended)

opensre integrations setup telegram

Interactive shell: /integrations setup telegram. The setup prompts for:

Bot token (required) — stored as TELEGRAM_BOT_TOKEN in .env and ~/.opensre/credentials.json
Default chat ID or @channelname (required) — written to .env as TELEGRAM_DEFAULT_CHAT_ID

Credentials are also saved to ~/.opensre/integrations.json via upsert_integration("telegram", ...). Both answers are checked before anything is saved, so a wrong token or a chat the bot was never added to fails here rather than silently at the first alert.

Setup confirms the bot can see the chat, not that it may post there. For a channel the bot still needs the Post Messages permission.

Option 2: Environment variables

TELEGRAM_BOT_TOKEN=<numeric-id>:<token-secret>
TELEGRAM_DEFAULT_CHAT_ID=<chat-id>
TELEGRAM_ALLOWED_USERS=123456789   # for two-way gateway chat

Variable	Description
`TELEGRAM_BOT_TOKEN`	Bot HTTP API token from BotFather. Required.
`TELEGRAM_DEFAULT_CHAT_ID`	Default delivery destination. Required for delivery to work.
`TELEGRAM_ALLOWED_USERS`	Comma-separated numeric user ids allowed for gateway chat.

Credential resolution. Telegram delivery surfaces resolve the bot token from the integration store first, then resolve_env_credential("TELEGRAM_BOT_TOKEN") (process env, then the credentials file). Chat id is non-secret: --chat-id → store default_chat_id → TELEGRAM_DEFAULT_CHAT_ID env (plain os.getenv).

Credentials

Create a bot with BotFather

BotFather is Telegram’s official bot for creating other bots.

Open Telegram and search for @BotFather. Open the chat and tap Start.
Send /newbot.
When prompted, send a display name for your bot (e.g. OpenSRE Alerts).
Send a username that ends in bot (e.g. opensre_alerts_bot). It must be globally unique.
BotFather replies with an HTTP API token of the form <numeric-id>:<token-secret>. Copy it — treat it like a password.

You can change the bot name, picture, and description later by sending /mybots to BotFather and selecting your bot.

Add the bot to a chat

Group chat
Channel
Direct message

Open the group where you want messages to land.
Tap the group name → Add members → search for your bot username → Add.
By default, bots in groups only see messages addressed to them, which is fine for delivery-only.

Open a chat with your bot directly (search its username) and send /start. The bot will not reply, but Telegram registers the chat so the bot can message you.

Find your `chat_id`

The chat ID identifies where the bot should post. It is required — without it the bot has nowhere to send anything.

Posting to a public channel? Skip this step — setup accepts the channel’s @name (for example @acme_alerts) directly. Private groups and DMs have no @name, so they need the steps below.

Send any message in the destination chat — for a channel, post anything; for a DM, send /start to your bot.

In a browser, open:

https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

In the JSON response, look for a chat.id field:
Chat type Format Example
Direct message with a user Positive integer 123456789
Group Negative integer -987654321
Large group or channel Negative integer starting with -100 -1001234567890
Copy the entire value, including the leading minus sign for groups and channels.

Chat type	Format	Example
Direct message with a user	Positive integer	`123456789`
Group	Negative integer	`-987654321`
Large group or channel	Negative integer starting with `-100`	`-1001234567890`

If getUpdates returns an empty array, post a fresh message in the chat and reload — Telegram only buffers recent updates.

Telegram tools

Tool	What it does
`telegram_send_message`	Send a message to the default chat or an explicit `chat_id`

{
  "name": "telegram_send_message",
  "arguments": {
    "chat_id": "-1001234567890",
    "message": "DB CPU is back below 70%; keeping the incident open for 10 minutes."
  }
}

The tool resolves the bot token from the integration store, then resolve_env_credential("TELEGRAM_BOT_TOKEN") (env then keyring). If chat_id is omitted, it sends through the configured default_chat_id. Delivery is an external side effect. Its result includes a stable status, sent, error_type, chat_id, reply_to_message_id, and message_length shape so follow-up tool calls can tell configuration failures from Telegram delivery failures.

Two-way chat gateway (DM text)

Skip this if you only need outbound delivery (alerts, cron reports). Setup + verify are sufficient for that.

v1 supports text-only direct messages (no groups, voice, or attachments).

Allow your Telegram user

Find your numeric user id with @userinfobot, then:

opensre messaging allow -p telegram -u 123456789
# or: TELEGRAM_ALLOWED_USERS=123456789

Interactive shell: /messaging allow -p telegram -u 123456789.

Use the numeric user id (Telegram’s from.id), not a @username and not the bot handle. Inbound authorization only ever matches the numeric id. The CLI rejects non-numeric Telegram ids, but older entries may still be wrong — check with /messaging status -p telegram.

DM pairing (optional)

opensre messaging pair -p telegram

Then DM your bot and send /pair <code>.

opensre messaging status -p telegram
opensre messaging revoke -p telegram -u 123456789

Start the gateway daemon

opensre gateway start

Command	What it does
`opensre gateway start`	Start the daemon (web, Telegram chat, task scheduler)
`opensre gateway start -f`	Run attached to the terminal instead
`opensre gateway status`	Show the daemon and each component’s state
`opensre gateway logs [-n N] [-f]`	Print (or follow) the daemon logs
`opensre gateway stop`	Stop the daemon

Also available in the REPL via /gateway start|status|logs|stop. Logs: ~/.opensre/gateway/gateway.log. If Telegram is not configured the daemon still runs the other components and status shows telegram: not configured. The gateway uses long polling — no public HTTPS URL or port forwarding is required for local use. Built-in commands: /new, /help, /pair <code>. The gateway uses the same headless agent harness as the interactive shell: the agent grounds its prompt in your configured integrations and calls their tools to answer. Cron deliveries use the outbound-only path — they do not require the gateway process.

Deploying the gateway to a remote host

Running the gateway on a server with make deploy-gateway (EC2) is different from local use: the remote host cannot read your local machine’s keychain. Guided setup stores the bot token (and your LLM API key) in the system keyring, which does not travel to the deployed instance. So make deploy-gateway validates that the required secrets are present as plaintext env vars in .env:

TELEGRAM_BOT_TOKEN=<numeric-id>:<token-secret>
TELEGRAM_ALLOWED_USERS=123456789
ANTHROPIC_API_KEY=...                    # or your provider's key env

If deploy reports MISSING: TELEGRAM_BOT_TOKEN even though local setup succeeded, copy the values into .env (or .env.deploy.example) for the deploy.

Scheduled delivery

Configure Telegram first (setup + verify — the gateway is not required).

Cron (recurring reports)

opensre cron add --kind github_pr_sweep --cron "0 9 * * 1-5" \
  --tz Asia/Kolkata --provider telegram --chat-id <chat_id>

See Cron.

Verify

opensre integrations verify telegram

Interactive shell: /integrations verify telegram or /verify telegram. This calls Telegram’s getMe endpoint. On success it reports the bot @username. It does not start a listening process and does not test two-way communication or delivery chat routing.

Troubleshooting

Verify only calls getMe, so it surfaces token-validity errors but cannot detect chat-routing problems. Delivery-time errors appear in OpenSRE logs as [telegram] post message failed: <description>.

Symptom	Fix
`Missing bot_token`	Set `TELEGRAM_BOT_TOKEN` and restart long-running processes.
`401 Unauthorized`	Token invalid/revoked — regenerate in BotFather and update credentials.
`chat not found` (delivery)	Re-add the bot and re-fetch `chat_id` from `getUpdates`.
`bot was kicked…`	Re-add the bot; channels need Post Messages admin permission.
Messages never arrive, but verify passes	Re-fetch `chat_id` — groups upgraded to `-100…` prefixes may have changed.
Gateway: `User <id> is not in the allowed users list`	Allow the numeric user id or complete `/messaging pair -p telegram`.

Security

Treat the bot token like a password; prefer ~/.opensre/credentials.json.
Use numeric user ids on the allow-list — never @username.
Prefer a dedicated bot for OpenSRE.
For remote deploy, put secrets in plaintext .env on the host (keyring does not travel).
Store secrets out of source control.

​Overview

​Prerequisites

​Setup

​Option 1: CLI setup (recommended)

​Option 2: Environment variables

​Credentials

​Create a bot with BotFather

​Add the bot to a chat

​Find your chat_id

​Telegram tools

​Two-way chat gateway (DM text)

​Allow your Telegram user

​DM pairing (optional)

​Start the gateway daemon

​Deploying the gateway to a remote host

​Scheduled delivery

​Cron (recurring reports)

​Verify

​Troubleshooting

​Security

Overview

Prerequisites

Setup

Option 1: CLI setup (recommended)

Option 2: Environment variables

Credentials

Create a bot with BotFather

Add the bot to a chat

Find your `chat_id`

Telegram tools

Two-way chat gateway (DM text)

Allow your Telegram user

DM pairing (optional)

Start the gateway daemon

Deploying the gateway to a remote host

Scheduled delivery

Cron (recurring reports)

Verify

Troubleshooting

Security