Blog
A step-by-step guide to Telegram server down alerts: BotFather, chat ids for private and group chats, message templates, quiet hours and one alert per outage.
To get Telegram alerts when your server is down, create a bot with @BotFather, send it a message or add it to a group, read the chat id from the Bot API, and let an external monitor call sendMessage whenever a check changes state. The bot setup takes about five minutes. The part that decides whether the alerts stay useful is everything after it: who receives them, what the message says, how nights are handled and how you prevent ten messages for one outage.
Telegram bots are accounts controlled through an HTTPS API. Your monitoring side holds a bot token, and every alert is a single POST request to https://api.telegram.org/bot<token>/sendMessage with a chat id and a text. There is no SDK needed and no server on Telegram's side to configure.
The important architectural point: the check must run somewhere other than the server it watches. A script on the box cannot report that the box has lost power, its network or its kernel. Run the check from a second machine, or better, from a monitoring service that probes from several regions.
Send one message per state change from a monitor that runs outside the server, not one message per failed check from the server itself. Almost every problem with noisy Telegram alerts comes from breaking one half of that rule.
/newbot, choose a display name (for example Example Ops Alerts) and a username that ends in bot, such as example_ops_alerts_bot. BotFather replies with a token like 7123456789:AAF.... Store it in a secret manager or environment variable, never in a repository. If it leaks, /revoke in BotFather issues a new one./start@example_ops_alerts_bot. With the default privacy mode, bots in groups only receive commands and messages that mention them, so a plain "hello" will not show up.getUpdates and read the chat object from the latest message.curl -s "https://api.telegram.org/bot$TG_TOKEN/getUpdates" | jq '.result[].message.chat | {id, type, title}'
{
"id": -1001234567890,
"type": "supergroup",
"title": "ops-alerts"
}Private chat ids are positive numbers. Group ids are negative, and supergroup ids start with -100. If the result is empty, send another message to the bot and call again, since updates are only kept for a limited time.
curl -s -X POST "https://api.telegram.org/bot$TG_TOKEN/sendMessage" -d chat_id=-1001234567890 -d parse_mode=HTML --data-urlencode "text=<b>TEST</b> alert path works"
A private chat fits a solo founder or a personal side project. Nobody else needs to see the alert, and you avoid the group privacy settings entirely.
A group is the better default as soon as two people share responsibility. Everyone sees the same alert, someone can reply "on it", and the history doubles as a rough incident log. A few rules keep groups useful:
ops-critical for production down and ops-warnings for slow responses or expiring certificates. People can then mute the warnings group without missing outages.message_thread_id to post into a specific topic per service.migrate_to_chat_id value. Update the configuration, then send a test message.The phone notification preview shows the first line and part of the second. Put state and target there, details below. A useful template:
<b>DOWN</b> api.example.com (production) Check: HTTPS GET /health, expected 200 Error: connection timeout after 10s Failing locations: 2 of 3 (Frankfurt, Virginia) Since: 03:14 UTC Runbook: https://wiki.example.com/runbooks/api
And the matching recovery message, sent as a reply to the original alert so the pair stays together in the chat:
<b>RECOVERED</b> api.example.com (production) Downtime: 7 min (03:14 to 03:21 UTC) Last error: connection timeout after 10s
To thread the recovery, store the message_id returned by the first sendMessage call and pass it in reply_parameters (or the older reply_to_message_id) when sending the recovery. Practical details:
parse_mode=HTML, escape <, > and & in error texts, otherwise the API rejects the message with a parse error and you get no alert at all.The Bot API has a disable_notification parameter. Set to true, the message arrives silently: it is in the chat, but the phone does not ring. That is the right tool for low-severity alerts at night.
silent=false
hour=$(date -u +%H)
if [ "$SEVERITY" != "critical" ] && { [ "$hour" -ge 21 ] || [ "$hour" -lt 6 ]; }; then
silent=true
fi
curl -s -X POST "https://api.telegram.org/bot$TG_TOKEN/sendMessage" -d chat_id="$TG_CHAT_ID" -d disable_notification=$silent --data-urlencode "text=$MSG" > /dev/nullTwo caveats. First, never silence the critical path: if production is down at night and someone is on call, the alert must make noise. Second, Telegram is a chat app. Phone do-not-disturb modes, a muted group or a dead battery will swallow the alert, and nobody acknowledges it. For real night paging, pair Telegram with a channel that can escalate, and define who is responsible in an on-call rotation that states what pages at night.
Duplicates have three typical sources: alerting on every failed check instead of on state changes, several systems sending for the same outage, and flapping services that go down and up every minute.
Keep state between checks and only send when it changes. Require at least two consecutive failures before sending DOWN, which also filters most single-packet glitches. A minimal checker for a second machine, run every minute from cron:
#!/usr/bin/env bash
URL="https://api.example.com/health"
STATE="/var/tmp/api-health.fails"
send() { curl -s -X POST "https://api.telegram.org/bot$TG_TOKEN/sendMessage" -d chat_id="$TG_CHAT_ID" -d parse_mode=HTML --data-urlencode "text=$1" > /dev/null; }
fails=$(cat "$STATE" 2>/dev/null || echo 0)
if curl -fsS -o /dev/null --max-time 10 "$URL"; then
[ "$fails" -ge 2 ] && send "<b>RECOVERED</b> $URL"
echo 0 > "$STATE"
else
fails=$((fails + 1))
echo "$fails" > "$STATE"
[ "$fails" -eq 2 ] && send "<b>DOWN</b> $URL failed 2 checks in a row"
fiThe -eq 2 is the key detail: the alert fires exactly once when the threshold is crossed, not on the third, fourth and fiftieth failure. A single checker in one location still produces false alarms when its own network has issues; checking from several regions and alerting only on agreement is covered in detail in how to reduce false positive alerts.
If your uptime monitor, a cron script and a log alert all post to the same group when the API dies, you get three messages with three wordings. Decide which system owns "server down" and let the others send only what they uniquely know, such as disk full or a failed backup.
For services that bounce, require several consecutive successes before sending RECOVERED, or add a cooldown so a new DOWN within ten minutes of a recovery is posted as a reply instead of a fresh alert. Telegram also throttles bots: its bot FAQ asks you to stay around one message per second per chat and no more than 20 messages per minute in a group. Beyond that the API answers with HTTP 429 and a retry_after value. An alert storm that hits this limit delays exactly the messages you need.
A self-built checker is fine for one or two endpoints. Once you have more, you are maintaining retries, multi-location checks, state storage and escalation yourself. m0nitor is one option for this: Telegram is among its supported alert channels, alongside email, Slack, SMS, PagerDuty and others, and checks run from distributed probes in several regions. Alert workflows decide what happens on a monitor event, for example notifying a Telegram chat, creating an incident or calling a webhook, and on-call schedules with do-not-disturb hours route alerts to whoever is responsible at that moment. Whatever tool you use, the rules above about message content, severity groups and state-based alerting still apply.
Usually the bot has not received a message it can see yet. In groups with privacy mode on, send a command addressed to the bot, such as /start@yourbot. Also check that no webhook is set on the bot, because getUpdates does not work while a webhook is active; deleteWebhook removes it.
Add the bot to the group, send a command that mentions the bot, then call getUpdates and read message.chat.id. Group ids are negative, and supergroup ids start with -100. If the group is later converted to a supergroup, the id changes and must be updated.
It delivers quickly, but it has no acknowledgement or escalation, and muted chats or phone do-not-disturb settings can hide alerts. It works well as a team notification channel. For critical night alerts, combine it with SMS or a paging tool and a defined on-call schedule.
Yes. The Bot API is a plain HTTPS endpoint, so a cron script with curl on a separate machine is enough. Keep the check off the monitored server, store state so you only alert on changes, and keep the bot token in an environment variable or secret store.