Telegram

Deliver investigation findings to a Telegram chat or channel.

Overview

OpenSRE’s Telegram integration delivers investigation findings 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 to receive findings.

Setup

Option 1: Onboarding wizard (recommended)

opensre onboard
# or
opensre integrations setup telegram

Interactive shell: /onboard or /integrations setup telegram.

Choose Telegram. The wizard 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. Every Telegram delivery surface — investigations, background RCA completion notifications, the scheduler, /watchdog, /hermes watch, and /watch — resolves the bot token the same way: 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.

1. Open Telegram and search for @BotFather. Open the chat and tap Start.
2. Send /newbot.
3. When prompted, send a display name for your bot (e.g. OpenSRE Alerts).
4. Send a username that ends in bot (e.g. opensre_alerts_bot). It must be globally unique.
5. 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

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

Channel

1. Open your channel and tap its name.
2. Tap Administrators → Add Administrator, search for your bot, and add it.
3. Grant the Post Messages permission. No other admin permissions are required.

Direct message

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.

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

2. In a browser, open:

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

3. 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.

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

Investigation 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 same credential chain as the watchdog: 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, investigation findings). 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, with Telegram-specific wiring:

• Prompt grounding — CLI reference, AGENTS.md, integration list, and investigation flow context
• Read-only evidence tools — live integration queries via the gather pass when integrations are configured
• Action tools — shell_run and investigation_start

Investigation delivery, background RCA completion notifications, watchdog alerts, and cron still use the outbound-only paths — 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, background, and watchdog delivery

Background investigation completion (RCA)

Configure Telegram first (setup + verify — the gateway is not required), then:

/background on
/background notify set telegram          # or: email,telegram
/investigate datadog

On completion the summary is posted as plain text to your default chat, truncated to Telegram’s 4,096-character limit. Confirm with /background show <task_id>. A notification problem never fails the investigation itself. See Background investigations.

Cron (recurring reports)

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

See Cron.

Watchdog (process threshold alarms)

opensre watchdog --pid <pid> [--max-cpu N] [--max-runtime D] [--max-rss S]

Interactive shell: /watch, /watches, /unwatch, /watchdog.

Hermes incident escalation

opensre hermes watch

See Hermes.

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.

Delivery test:

opensre investigate --input tests/e2e/kubernetes/fixtures/datadog_k8s_alert.json

Findings should appear in the configured chat. Long reports are truncated to Telegram’s 4,096-character message limit.

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.
Findings 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.