This Stashboard Telegram notifications setup guide takes you from an empty chat to a phone that buzzes when a service goes down, a Docker image gets a new release, or a Proxmox host has updates waiting. You’ll create a bot, find your chat ID, fill in one card in Stashboard and switch on the alerts you want. 📲
It’s the companion to the Stashboard SMTP email notifications guide. Email gives you a searchable record; Telegram is for “look at this now”. The two channels run side by side, and a failure on one never blocks the other.
How Stashboard Telegram Notifications Setup Works
Telegram lives on the dedicated Notifications page that V5.0.3 split off from the Account page. In current builds it sits under Settings → Notifications, next to the SMTP and Apprise cards.
Three things set the Stashboard Telegram notifications setup apart from the SMTP card:
- It’s per user. SMTP and Apprise are app-wide, but the bot token and chat ID are stored on your own Stashboard account. Every alert goes to the owner of the service, watch or Proxmox host that raised it, through that owner’s bot and chat.
- It’s outbound only. Each message is one HTTPS call to the Bot API’s sendMessage method, with a 10-second timeout and link previews off. No webhook, no inbound port.
- Changes apply at once. Settings are read on every send, so nothing needs a restart.
The Stashboard Telegram notifications setup has two layers of switches. A master switch on the Notifications page decides whether Telegram is used at all. A per-item switch on each service, Docker watch or Proxmox host decides whether that item uses it. Both must be on.
Prerequisites
Before you start the Stashboard Telegram notifications setup, check that you have:
- Stashboard running, signed in as the account that owns the items you want alerts for.
- A Telegram account and the Telegram app on your phone or desktop.
- Outbound HTTPS from the Stashboard container to
api.telegram.orgon port 443. - At least one thing to watch: a service with a health check, a Docker watch, or a Proxmox host.
Step 1 — Create a Bot for Your Stashboard Telegram Notifications Setup 🤖
Stashboard sends messages as a bot you own, created as the Telegram bot tutorial describes. If you followed the qBittorrent Telegram notifications guide, you can reuse that bot.
- In Telegram, open a chat with @BotFather, the official bot for creating bots.
- Send
/newbot. - Enter a display name, such as
Stashboard Alerts. - Enter a username. It must end in
bot, for examplevahac_stashboard_bot. - BotFather replies with a token like
123456789:AAH.... Copy it.
⚠️ The token is a password. Anyone who has it can send messages as your bot and read what people send to it. Keep it out of chats, screenshots and public issues. If it leaks, send /revoke to BotFather for a new token, then update Stashboard.
Step 2 — Find Your Chat ID 🔎
The chat ID is the second half of the Stashboard Telegram notifications setup: it tells the bot where to post. A bot can’t message you first, so you start the conversation.
- Open your new bot’s chat and press Start (this sends
/start). - In a browser, open this URL with your token in place of
<TOKEN>:
https://api.telegram.org/bot<TOKEN>/getUpdates
- Find
"chat":{"id":...}in the JSON. For a private chat it’s a positive number, such as123456789. That’s your chat ID.
If the result is empty ("result":[]), send the bot another message and reload. getUpdates only returns recent messages, and it doesn’t work while a webhook is set on the bot. A fresh bot has none.
Sending alerts to a group or channel
- Group: add the bot to the group and send
/start@your_bot_username. Privacy mode lets a bot see only commands and mentions by default, so a plain message may not show up. Group IDs are negative, and supergroup IDs start with-100. - Channel: add the bot as an administrator that can post. Use the numeric
-100…ID, or@channelnamefor a public channel.
⚠️ Everyone in that group or channel sees every alert, including internal hostnames, URLs and error text. Use a private chat unless you share on-call duty.
Step 3 — Enter the Token and Chat ID in Stashboard ⚙️
Open Settings → Notifications and find the Telegram notifications card. It has three controls:
- Bot token: a password field with an eye icon. Paste the full BotFather token, including the part before the colon.
- Chat ID: the number from Step 2, with the minus sign for groups and channels.
- The master checkbox. In 10.5 its label reads Send notifications when a service becomes unavailable, which undersells it. It’s the master switch for every Telegram message, Docker and Proxmox alerts included. Newer builds relabel it Enable Telegram notifications.
Tick the checkbox and click Save Telegram settings. You should see Telegram settings saved. That completes the core Stashboard Telegram notifications setup; the rest is choosing what to send.
⚠️ The checkbox needs both fields. If the token or chat ID is empty, the server stores the switch as off without an error, and the box is unticked after the page reloads. Fill in both fields and save again.
⚠️ This isn’t the SMTP password field. The SMTP card keeps a stored password when you leave its field blank. The Telegram card loads the stored token back into the field instead, so if you clear it and save, the token is deleted.
The token is encrypted at rest with the same AES-256-GCM key as your SMTP password, in the stashboard-data volume. The Telegram endpoints refuse personal access tokens, so a leaked API token can’t read it.
Step 4 — Turn On the Per-Item Toggles 🎛️
With the master switch on, pick which items use Telegram. Your Stashboard Telegram notifications setup has one switch per item type.
Services: “Notify when service goes offline”
Open a service, go to its Healthcheck tab, and tick Healthcheck the main URL (or the additional URL). Then tick Notify when service goes offline. That checkbox stays greyed out until a health check is on.
On a service, this one switch covers every channel, with no separate Telegram tick. For many homelabs, service-down alerts are the whole point of a Stashboard Telegram notifications setup, and with the master switch on they go straight to Telegram.
Docker watches: “Send a Telegram message when an update is available”
In a Docker watch’s form, tick Send a Telegram message when an update is available. It’s separate from the email and Apprise ticks, so any mix works. It stays greyed out until the master switch is saved with both fields filled. The Docker update monitoring guide covers watches in depth.
Proxmox hosts: “Also notify via Telegram”
Edit a Proxmox host and tick Also notify via Telegram. It covers both pending-update and node-health alerts for the host. It isn’t greyed out when Telegram isn’t set up, but the master switch still decides. Node-health alerts must also be turned on in the node modal’s Alerts tab, where they’re off by default.
What the Stashboard Telegram Notifications Setup Delivers 📨
A finished Stashboard Telegram notifications setup delivers four kinds of message. These are the templates from the code.
Service down
🔴 Service unavailable: Jellyfin
Main URL: http://192.168.1.111:8096
Error: <error text from the probe>
If the additional URL also fails, it gets its own message. Services never send a “back up” message; only node-health alerts announce a recovery.
Docker update available
🔔 Update available for Immich
Image: ghcr.io/immich-app/immich-server:release
Container: immich_server
Current: sha256:…
Latest: sha256:…
Release notes: https://github.com/…
Pull and recreate the container at your convenience.
The Release notes line only appears for GHCR images where Stashboard matched a GitHub release.
Proxmox updates pending
🔔 Updates pending on Proxmox host pve (14 total)
• pve (node): 9 update(s)
• jellyfin (CT 101): 5 update(s)
Apply them at your convenience.
Containers with monitoring turned off in their Watch tab are left out. The Proxmox LXC update monitoring guide explains how the counts are collected.
Node health alerts
A 🔴 (critical) or 🟠 (warning) Node health alert on Proxmox host … lists each firing category (CPU, Memory, Storage, Thermal, SMART, Network) with its value, threshold and first-seen time in UTC. When everything is back to normal, you get ✅ Node health recovered. The Proxmox node monitoring guide covers thresholds and categories.
Throttling in the Stashboard Telegram Notifications Setup 🧯
Throttling keeps a Stashboard Telegram notifications setup quiet. Each event type has its own anti-repeat rule, and Telegram keeps its own key, separate from email and Apprise:
- Service down fires once, on the change into Down. A service must first fail the Failure threshold of consecutive scans (default 3, at a 60-second interval, with 2 retries inside each probe), all set under Settings → Health checks. It doesn’t repeat while the service stays down.
- Docker updates fire once per new image digest. A later release means a new message.
- Proxmox updates fire when the pending counts change. 14 updates becoming 15 sends a fresh list, but the same 14 don’t repeat.
- Node alerts fire when the set of active alerts changes, once a problem persists for three evaluations in a row (they run about every 5 minutes), and once more when it clears.
For Docker, Proxmox and node alerts, the key is saved only after Telegram accepts the message, so a failed send is retried on the next check. Service-down alerts are different: the status change is recorded either way, so if api.telegram.org is unreachable at that moment, that alert is lost.
Telegram’s bot rate limits (about one message per second per chat, 20 per minute in a group) are far above what a homelab sends.
How to Verify Your Stashboard Telegram Notifications Setup ✅
The Telegram card has no Send test button (the Apprise card does), so verify your Stashboard Telegram notifications setup in two steps.
1. Test the bot outside Stashboard
This checks the bot half of your Stashboard Telegram notifications setup. From a shell on the Docker host, send a message with the same token and chat ID:
curl -s -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
-d chat_id=<CHAT_ID> \
-d text="Stashboard test"
"ok":true plus a message in Telegram means the credentials work and the host can reach Telegram. "ok":false comes with a description that says what’s wrong.
2. Trigger a real alert end to end
- Add a throwaway service named
Telegram testwith the Main URLhttp://127.0.0.1:9. Nothing listens on port 9 inside the Stashboard container, so the probe fails fast. - On its Healthcheck tab, tick Healthcheck the main URL and Notify when service goes offline, then save.
- Reopen the service and click Check now on the Healthcheck tab.
A manual Check now applies the result immediately and skips the failure threshold. The service flips to Down, and 🔴 Service unavailable: Telegram test should arrive within seconds. If the background scan got there first, the message is already in your chat.
To test again, point the URL at something that responds, click Check now to bring it Up, then break it again. Delete the test service when you’re done.
Troubleshooting Stashboard Telegram Notifications Setup 🛠️
A broken Stashboard Telegram notifications setup almost always leaves a trace in the logs, with the HTTP status Telegram returned:
docker logs stashboard-app 2>&1 | grep -i telegram
Look for lines like Failed to send Telegram notification for service …. The log shows the status code but not Telegram’s explanation, so rerun the curl test to see the description.
- 401 Unauthorized: the token is wrong or was revoked. Paste the current token from BotFather.
- 400 Bad Request, “chat not found”: wrong chat ID, a missing minus sign, or the bot isn’t in that group or channel.
- 403 Forbidden: you never pressed Start in the bot’s chat, you blocked the bot, or it was removed from the group.
- 400 after a group upgrade: a group that becomes a supergroup gets a new
-100…ID. Run getUpdates again and save the new ID. - Timeouts or DNS errors: the container can’t reach
api.telegram.org:443. Check the firewall, DNS and any proxy. - Docker watch checkbox greyed out: the master switch isn’t saved, or a field is empty. Its tooltip says “Account → Notifications”, an old name for Settings → Notifications.
- No message and no log line: a switch is off. Check the master checkbox, the per-item tick and the health check. Also check that the service wasn’t already Down, since alerts fire only on the change.
Risks of a Stashboard Telegram Notifications Setup ⚠️
A Stashboard Telegram notifications setup moves homelab data off your network, so weigh these:
- Alerts leave your LAN. Service names, internal URLs, IP addresses, image names and error text are stored on Telegram’s servers. Bot chats are cloud chats, not end-to-end encrypted.
- The token reaches your browser. Unlike the SMTP password, the settings page loads the decrypted token, so anyone using your signed-in session can reveal it with the eye icon. Protect the account with TOTP (V10.3) or SSO (V10.5).
- Backups hold the token in plain text. A Settings → Backup / Restore export decrypts secrets so it can be restored on another instance. Store that file like a password vault.
- Telegram needs the internet. If your WAN link or DNS is down, the alert you most want can’t leave. Pair Telegram with email, or with a local Apprise target such as a self-hosted ntfy server.
- A lost data volume means re-entering the token. Without the key in
stashboard-data, the stored token can’t be decrypted. Get a new one from BotFather and paste it in.
Stashboard Telegram Notifications Setup FAQ
Can each Stashboard user get their own Telegram alerts?
Yes. Each Stashboard Telegram notifications setup is per user: the token, chat ID and master switch live on your account, and alerts go to the owner of the item that raised them.
Can I get alerts on Telegram and email at the same time?
Yes. The channels are independent, with separate ticks for Docker watches and Proxmox hosts and separate throttle keys. Pair your Stashboard Telegram notifications setup with the SMTP email guide and turn on both.
Does the Stashboard Telegram notifications setup have a test button?
Not yet. Use the curl call and the throwaway Check now service from the verification section.
Does a Stashboard Telegram notifications setup need an open port or a webhook?
No. Stashboard only makes outbound HTTPS calls to api.telegram.org. Nothing listens for Telegram.
Bottom Line
A Stashboard Telegram notifications setup takes about ten minutes: create a bot with BotFather, read your chat ID from getUpdates, save both on Settings → Notifications with the master switch on, then tick Telegram on the services, watches and Proxmox hosts you care about. Test it with curl and a throwaway Check now, and keep email or a local Apprise target for when the internet itself is the outage. 🚀
New to Stashboard? Start with the homelab dashboard overview. Stashboard is open source: code on GitHub, image on Docker Hub.
