Blog

Telegram alerts when your server is down: BotFather setup, chat id, quiet hours and no duplicate messages

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.

How Telegram server alerts work

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.

How to set up Telegram alerts when your server is down

  1. Create the bot. Open a chat with @BotFather, send /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.
  2. Give the bot a chat to write to. Bots cannot start conversations. For a private chat, open the bot and press Start. For a group, add the bot as a member and send a message that it can see, for example /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.
  3. Find the chat id. Call 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.

  1. Send a test message. Confirm the token and chat id work before wiring anything to them.
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"
  1. Connect the monitor. Either paste token and chat id into your monitoring tool's Telegram integration, or call the API from your own checker as shown further below.

Group or private chat: which one should receive alerts?

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:

  • Separate groups by severity, for example ops-critical for production down and ops-warnings for slow responses or expiring certificates. People can then mute the warnings group without missing outages.
  • If you use a forum-style group with topics, pass message_thread_id to post into a specific topic per service.
  • Expect the chat id to change when a regular group is upgraded to a supergroup. The old id stops working and the API returns a migrate_to_chat_id value. Update the configuration, then send a test message.
  • Channels work too, but the bot must be an admin and nobody can reply in context. For alerting, a group is usually more practical.

What should a server down alert message contain?

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:

  • With 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.
  • Messages are limited to 4096 characters. Never paste full stack traces or response bodies; truncate to a few hundred characters.
  • Always state the environment. "DOWN api" from staging at 3 a.m. wakes people for nothing.
  • Use UTC or say which timezone, especially when the team is distributed.

Quiet hours without missing real outages

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/null

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

How to avoid duplicate notifications

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.

Alert on transitions, confirmed by retries

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"
fi

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

One sender per signal

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.

Damp flapping and respect rate limits

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.

Using a monitoring service instead of your own script

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.

FAQ

Why does getUpdates return an empty result?

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.

How do I get the chat id of a Telegram group?

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.

Is Telegram reliable enough for on-call paging?

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.

Can I send Telegram alerts without a third-party service?

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.

Product

  • Pricing
  • Features
  • Integrations
  • Security
  • Free network check

Features

  • Uptime monitoring
  • Status pages
  • Alert workflows
  • Incident management
  • Dependencies
  • AI assistant
  • Global infrastructure
  • On-call schedules
  • Enterprise SSO

Use cases

  • Websites for free
  • Cron jobs
  • SSL certificates
  • Databases
  • IP blacklists
  • GDPR compliance

Resources

  • What is a status page?
  • Documentation
  • API
  • MCP server
  • Monitoring glossary
  • Free tools
  • SLA calculator
  • SSL checker
  • DNS lookup
  • Blog
  • Changelog
  • About
  • Contact

Compare

  • Free uptime monitoring
  • UptimeRobot
  • Better Stack
  • Pingdom
  • StatusCake
  • Uptime Kuma
  • Hyperping
  • Atlassian Statuspage
  • Instatus
  • Cachet
  • Freshping