Telegram

Telegram is the default alert channel: free, instant, and reachable from every platform.

Setup

Create a bot — message @BotFather, send /newbot, follow the prompts, and keep the token.
Message your bot once. Telegram bots cannot start a conversation. If you never message it, it can never message you.
Get the chat id from https://api.telegram.org/bot<your-token>/getUpdates — look for chat.id. For a group, add the bot to the group first; group ids are negative numbers.

Configure Watcher:

telegram_bot_token=<your-bot-token>
telegram_chat_id=<your-chat-id>

Verify with curl -s https://<your-host>/config/status — both should show true — then force a run on a watch you expect to fire.

Routing watches to different chats

One bot can serve many destinations. Override the chat per watch:

channels:
  - { type: telegram, chatId: "-1001234567890" }

A bare telegram uses telegram_chat_id. This is how you send work watches to a team group and personal ones to your own chat.

Health alerts

Set TELEGRAM_ADMIN_CHAT_ID to send operational messages — a watch whose sources all failed, a crashed run — somewhere separate:

TELEGRAM_ADMIN_CHAT_ID=<your-admin-chat-id>

They are formatted distinctly (⚠️ Watcher health) so they never look like an event alert. Unset, they go to the normal chat.

What an alert looks like

🔔 Framework stable releases

Version 2.0 has been published as a stable release on the official blog.

"v2.0 is now generally available" (2026-08-12)

https://example.com/blog/v2-ga

Weak-tier alerts replace the header with ❓ Possible update (unconfirmed) — … so the two are never confused.

Link previews are left enabled, which usually gives you a useful thumbnail of the source page.

Failure behaviour

A Telegram failure does not lose the alert: if every channel fails, the alert is stored and replayed on the next run, up to five attempts. See Failures and retries.

Common problems

Symptom	Cause
Alerts print to the console	Token or chat id not configured
`400 Bad Request` from the API	Wrong chat id, or you never messaged the bot
`403 Forbidden`	The bot was blocked or removed from the group
Alerts go to the wrong chat	A per-watch `chatId` override

More: Alerts are not arriving.