Watch a service and get a Telegram alert

Updated 2026-10-10

This guide sets up Gatus to check your services and message you on Telegram when one fails. It runs on the server that hosts the services.

Create a bot of its own

Open Telegram and message @BotFather. Send /newbot and follow the prompts. BotFather returns a token. Save the token in a password manager, not in a repo.

Give the monitor its own bot. I first reused my assistant’s bot, and its alerts probably never arrived. The assistant’s bot lived on a different Bot API server, and Gatus sent the token to api.telegram.org, which rejected it. A separate bot on the normal API fixed it. I did not check the old logs, so the cause is a hypothesis.

Send your new bot one message. Then open https://api.telegram.org/bot<TOKEN>/getUpdates and read chat.id from the result. That number is the id in the config below.

Run Gatus

services:
  gatus:
    image: twinproduction/gatus:latest
    container_name: gatus
    restart: unless-stopped
    cap_add:
      - NET_RAW
    volumes:
      - ./config:/config
      - ./data:/data
    networks: [web]

networks:
  web:
    external: true

NET_RAW lets Gatus send ICMP pings. Drop it if you only check HTTP.

Write the config

Put this in ./config/config.yaml:

alerting:
  telegram:
    token: "<BOT_TOKEN>"
    id: "<CHAT_ID>"
    default-alert:
      failure-threshold: 2
      success-threshold: 2
      send-on-resolved: true

endpoints:
  - name: vault.example.com
    url: "https://vault.example.com/alive"
    interval: 2m
    conditions:
      - "[STATUS] == 200"
    alerts:
      - type: telegram

  - name: home machine
    url: "icmp://100.64.0.10"
    interval: 2m
    conditions:
      - "[CONNECTED] == true"
    alerts:
      - type: telegram

Each value means one thing:

failure-threshold: 2 sends an alert after two failed checks in a row. One slow response does not wake you.
success-threshold: 2 and send-on-resolved: true send one message when the service recovers.
interval: 2m means a dead service is noticed in about four minutes.

Add the hard cases

Some checks need more than a status code. My DNS resolver answers DoH only in wire format, so the check sends a real query and a header:

  - name: dns.example.com (DoH)
    url: "https://dns.example.com/dns-query?dns=AAABAAABAAAAAAAABmdvb2dsZQNjb20AAAEAAQ"
    headers:
      Accept: application/dns-message
    interval: 2m
    conditions:
      - "[STATUS] == 200"
    alerts:
      - type: telegram

The JSON form of that endpoint returns 400, so a check written with ?name= would alert for the wrong reason.

Gatus serves a status page. Add a site block with import sso, as in Build the one-VPS stack. Do not use an unprotected status page to list your services.

Check the result

Run docker compose up -d, then stop one monitored container. After about four minutes you should get a message. Start the container again, and a recovery message follows.

Gatus reads its config only at start. Run docker restart gatus after each edit.