Telegram alerts when something at home goes down (Uptime Kuma + a bot in 10 minutes)

I have a Raspberry Pi at home running several services (a password manager, a Git server, an app to log my workouts…) and Uptime Kuma watching all of them. Uptime Kuma is a free tool that checks every so often whether your services respond, and draws you a nice coloured bar.

The problem: a coloured bar is useless if nobody looks at it. I realised this when I found out my backups had been failing for three days. Uptime Kuma knew. I didn’t, because I had no notifications set up.

So let’s fix it: make Uptime Kuma message you on Telegram when something goes down, and again when it comes back.

What you need

• Uptime Kuma up and running (mine runs in Docker on the Pi).
• A Telegram account.
• Ten minutes.

Step 1: create a bot with BotFather

On Telegram, bots are created by talking to another bot: @BotFather.

1. Open a chat with @BotFather and send /newbot.
2. It asks for a display name. I called mine Home Alerts.
3. Then a username ending in bot, for example my_home_alerts_bot. If it’s taken, try another.
4. BotFather replies with a token that looks like this: 123456789:AAH....

That token is the bot’s password. Anyone who has it can send messages as the bot. Don’t paste it in forums, screenshots or repositories.

Tip: create a bot just for alerts. If you already have a bot for something else, don’t mix them: that way, if you change one some day, you won’t break the other.

Step 2: talk to the bot

Lots of people skip this. A Telegram bot can’t message you unless you’ve talked to it first. Search for your bot by its username, open the chat and press Start. Send it a “hi” too, it costs nothing.

Step 3: get your chat ID

Uptime Kuma needs to know which chat to write to. It has a button that finds it for you (you’ll see it in the next step), but if you want to do it by hand, ask the bot for its latest messages:

curl -s "https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates"

In the response, look for "chat":{"id":123456789,...}. That number is your chat ID. If the response is empty ("result":[]), you haven’t written to the bot yet: go back to step 2.

Step 4: set up the notification in Uptime Kuma

In the Uptime Kuma web UI, go to Settings → Notifications → Setup Notification:

• Notification type: Telegram.
• Friendly name: something you’ll recognise, like Telegram - Home Alerts.
• Bot token: the one from step 1.
• Chat ID: the one from step 3, or press the button to fetch it automatically.
• Tick Default enabled, so new monitors get it switched on.
• Tick Apply on all existing monitors.

That last checkbox is the key to this whole article. If you don’t tick it, the notification gets created but no monitor uses it, and you’ll keep missing everything. It’s very easy to overlook.

Press Test: you should get a test message in the bot’s chat. If it arrives, Save.

Step 5: check that it really works

The Test button only proves the bot can message you. It doesn’t prove that a monitor going down will trigger the alert. For that, cause a real outage on something unimportant.

I did it with a web dashboard I run on the Pi (as a systemd service):

sudo systemctl stop centro-mando
# ...wait for the alert...
sudo systemctl start centro-mando

In under a minute I got this:

[Centro de mando] [🔴 Down] connect ECONNREFUSED 192.168.1.50:8090

And after starting it again:

[Centro de mando] [✅ Up] 200 - OK

Now the whole chain is proven to work.

Settings that will save you headaches

• Remove alerts from things that aren’t always on. If you monitor your laptop, you’ll get a message every time you switch it off. Open that monitor and untick the notification.
• Retries before alerting. In each monitor you can make it retry once or twice before marking it as down. It avoids false alarms from a one-second glitch.
• Watch your scheduled jobs too. Uptime Kuma has push monitors: your script tells Kuma it finished fine. If one day it doesn’t, Kuma marks it as down and messages you. Perfect for nightly backups.

Wrapping up

Monitoring without alerts is like an alarm without a siren. With a Telegram bot and two checkboxes ticked correctly, your home server goes from “I’ll find out eventually” to pinging your phone in under a minute.