Telegram notifications from Uptime Kuma: bot setup and best practice

Telegram is unusual among the chat platforms Uptime Kuma integrates with: it is primarily a mobile app, it offers free bots without any organisational setup, and it is just about universal enough among technical UK audiences that it makes a reasonable fallback or even primary mobile-alert channel. This guide walks through setting up Telegram bot notifications for Uptime Kuma, the patterns that make them useful rather than a novelty, and the operational considerations UK teams run into. If you are new to Uptime Kuma itself, start with our plain-English introduction.

Why Telegram for monitoring alerts

Telegram is not the first channel most teams reach for. Slack and Microsoft Teams are more common in UK engineering organisations; email is more universal; dedicated paging tools handle out-of-hours escalation more rigorously. Telegram sits in a specific niche: mobile-first, instant-delivery, group-friendly alerting at zero cost.

The situations where Telegram earns its keep:

Freelancers and very small teams. One or two people running a handful of customer projects. Setting up a dedicated Slack workspace for two people is overkill; Telegram works the moment everyone has the app installed.

Agencies monitoring multiple clients. A UK agency looking after 30 customer sites can have one Telegram group per client, each with the client included, so incidents become visible to everyone who cares about that specific site immediately.

Backup mobile channel. For teams that primarily use Slack or email, Telegram works well as a belt-and-braces mobile channel. When the on-call engineer is in a cinema with Slack silenced, a Telegram message breaks through in a way email rarely does.

Homelab and hobby monitoring. If your Uptime Kuma instance is watching personal infrastructure, Telegram delivers alerts to your pocket without any of the organisational overhead of commercial tooling.

For broader alerting strategy — when Telegram is appropriate vs when you want something more structured — our notification strategy guide covers the trade-offs.

Creating a bot with BotFather

Telegram's bot ecosystem is managed by a single built-in bot called BotFather. To create a new bot:

1. Open Telegram and search for the username @BotFather. Start a chat with it.
2. Send /newbot. BotFather asks for a display name (what users see) and a username (ending in bot, for example YourBrandAlertsBot).
3. Once the bot is created, BotFather returns a long token that looks like 123456789:ABCdefGhiJKlmNopQrsTuVwxYz. Copy this immediately. Treat it as a secret — anyone with the token can send messages as the bot.
4. Optionally, set a description and avatar via BotFather's /setdescription and /setuserpic commands. These appear to anyone who opens the bot's profile.

The bot itself cannot initiate conversations — it can only reply to users (or groups) that have first messaged it. This is a deliberate Telegram design to prevent spam, and it has one important consequence for monitoring: the chat that is going to receive alerts must send at least one message to the bot before Uptime Kuma can post to it. More on this in the next section.

Finding your chat ID

Telegram bots address messages by chat ID — a numeric identifier for either a personal chat or a group. There are a few ways to find yours.

Method 1: Message the bot directly, then hit its API.

1. In Telegram, open a chat with your new bot and send any message — /start is conventional.
2. In a browser, visit https://api.telegram.org/bot/getUpdates, replacing the placeholder with the bot token. (HTTPS, case-sensitive.)
3. The JSON response includes a chat object with an id field. That is your chat ID.

Method 2: Use a helper bot. Several community-built bots (search for @userinfobot or similar) reply with your personal chat ID when you message them. Useful for the personal-chat case.

Method 3: For group chats. Add your monitoring bot to the group, send a message mentioning the bot, and then hit getUpdates as above. The chat ID for a group is a negative number — include the minus sign when you configure Uptime Kuma.

Chat IDs never change once assigned, so this is a one-time exercise per destination. Save the chat ID somewhere convenient alongside the bot token.

Two quick gotchas worth calling out. First, the chat ID returned by getUpdates only appears if there has been recent activity in the chat — if you created the bot hours ago and never messaged it, the response may be empty. Sending any fresh message to the bot immediately before you hit getUpdates is the fix. Second, getUpdates in polling mode may not return updates if the bot has webhook mode enabled; if you cannot see updates, remove any webhook via deleteWebhook first.

Sending alerts to a group chat

Personal-chat alerts reach one person; group alerts reach everyone in the group. For a team, group chats are almost always the right choice.

1. Create a group in Telegram (or use an existing one).
2. Add the monitoring bot to the group — tap the group name, Add Member, search for the bot username.
3. By default, Telegram bots in groups cannot read messages (a privacy setting called "privacy mode"). This does not prevent them from sending messages, which is what you want for Uptime Kuma. You can leave privacy mode on.
4. Send a message in the group (any message), then retrieve the chat ID via getUpdates. The group chat ID is the negative number.

A subtle point: if you later convert the group to a supergroup (which Telegram does automatically once a group exceeds 200 members or is given additional features), the chat ID changes from a simple negative number to a prefix of -100 followed by the internal group ID. Supergroups are common and harmless, but if alerts suddenly stop arriving, check whether the group was upgraded and update the chat ID accordingly.

Configuring Uptime Kuma

In Uptime Kuma, add a new notification channel, select Telegram as the type. The form asks for:

• Friendly Name: whatever you want to call this channel in the Uptime Kuma UI.
• Bot Token: the token from BotFather.
• Chat ID: the numeric ID of the destination chat (positive for personal, negative for groups).
• Message Thread ID: optional, for forum-style supergroups where alerts should land in a specific topic.
• Disable Notification: if checked, messages arrive silently (no sound or vibration on the receiver's device).
• Protect Content: if checked, recipients cannot forward or copy the message content out of Telegram.

Save, then press Test. The bot should post a test message to the target chat within a second. If it does not, the three most common causes are: a wrong bot token, a wrong chat ID (especially missing the minus sign for group chats), or the destination chat has not messaged the bot yet so the bot cannot post to it.

Silent alerts for low-priority notifications

Telegram's notification system has a specific feature that makes it particularly well-suited for low-priority alerts: silent messages. A message with the disable_notification flag set arrives on the recipient's device without a sound, without a vibration, and (on most configurations) without a push notification — it simply appears in the chat when the recipient next opens Telegram.

This is a better fit than email for low-priority alerts because it:

• Still reaches the recipient when they open the app, unlike email which may sit buried
• Does not wake them up at 3am for a certificate-expiry warning that can wait
• Keeps the pattern of "Telegram = monitoring alerts" consistent, so the recipient does not need to check multiple channels

A typical UK pattern is to have two Telegram notification channels in Uptime Kuma pointing at the same chat — one for critical alerts with notifications enabled, one for informational alerts with Disable Notification ticked. The chat receives both; only the critical ones make a noise.

Message formatting

Uptime Kuma sends Telegram messages in Markdown format. This means you can make parts of the alert bold, italic, or monospaced, and include links that render as clickable tap-targets in the Telegram client.

The default template is reasonable. Customisations worth considering:

• Bold the monitor name at the start of the message so it is visible in chat previews on the notification lock screen
• Link to the monitor's Uptime Kuma page so the recipient can tap through to see history
• Include the failure reason in monospace (backticks) so error strings render clearly
• Include tags so the recipient immediately knows which environment or team the alert relates to

Telegram supports links with custom anchor text using the standard Markdown syntax. If your Uptime Kuma instance is on a public URL, linking to the monitor's detail view gives one-tap access from the alert to the full context. The link format is [monitor history](https://your-kuma-url/dashboard/123).

The second flavour Telegram supports, HTML formatting, is an alternative to Markdown with slightly different rules around escaping. Uptime Kuma defaults to Markdown mode; HTML mode is available if you hit Markdown edge cases that prove awkward to escape. For most UK deployments the default works fine and there is no reason to switch.

Media attachments are not supported by Uptime Kuma's built-in Telegram integration — alerts are text-only. If you need screenshots or charts in the alert, route through a webhook and a small intermediary service that calls Telegram's sendPhoto endpoint. For most monitoring use cases, text alerts with a link to the Uptime Kuma dashboard are entirely sufficient.

One limitation worth knowing: Telegram's Markdown parser is strict about certain characters. Underscores, asterisks and square brackets in the alert text (for example in a monitor name like checkout_api) can break rendering if they are not escaped. Uptime Kuma handles this automatically in most cases, but if you see alerts with partial rendering or a parse error, the cause is usually an unescaped special character in a dynamic field.

Operational patterns for UK teams

Three patterns that work well in real UK deployments.

Pattern 1: One team group, multiple notification channels. A single Telegram group for the engineering team, with two Uptime Kuma channels — one with notifications enabled for critical alerts, one silent for informational. Everyone sees everything; only the critical ones interrupt.

Pattern 2: Per-client or per-service groups. Agencies and MSPs often have one group per client, with the client invited. Uptime Kuma has one notification channel per client pointing at the relevant group. Each client sees alerts about their own services only; internal engineering sees everything via a master group that includes all alert channels.

Pattern 3: Out-of-hours escalation. Chat and email cover working hours. Telegram covers out-of-hours — specifically, on-call engineers have the Uptime Kuma bot on their phone with sound enabled, so critical alerts wake them up if necessary. Combined with a paging tool for the most severe issues, this provides graduated escalation.

If you are also routing alerts to email and chat platforms, the SMTP notifications guide and our Slack and Teams alerts guide are the companion pieces to this one. Using all three in combination is a very reasonable full-stack alerting setup for most UK SMEs.

Pattern 4: Solo developer monitoring. A single developer monitoring their own side projects or homelab gets excellent value out of Telegram alone. The bot sits in a personal chat, critical alerts sound, informational alerts arrive silently, and the whole setup costs nothing. This is the archetypal "hobby-scale monitoring" configuration and it works extremely well for what it is.

Pattern 5: Multi-platform on-call handover. Some UK teams operate a follow-the-sun or week-on/week-off handover. Rotating the on-call engineer between weeks is easy in Telegram — the outgoing engineer removes themselves from the alert group, the incoming engineer is added, and the bot continues sending to the same group regardless. Paired with a tagging convention in Uptime Kuma (tags like @on-call in alert messages), this keeps the on-call visible without ad-hoc reconfiguration of the monitoring itself.

Pitfalls to avoid

A handful of failure modes come up repeatedly when teams adopt Telegram for monitoring.

Bot token leaked in a config file. The bot token is equivalent to a password. Exposing it (for example by committing an Uptime Kuma config export to a public repository) gives anyone the ability to post messages as your bot. If this happens, regenerate the token via BotFather's /revoke command and update Uptime Kuma.

Bot unable to post because the chat has not initiated. New Telegram group or personal chat, bot added but nobody has messaged it yet — messages fail silently with a 403 error. Send any message in the chat first, then retry.

Chat ID changed after supergroup conversion. Alerts stop arriving after the group grows past a certain size. The chat ID needs updating to the new -100... format.

Every alert waking everyone up. If every alert is critical, nothing is critical. Use the Disable Notification option to separate informational from urgent, and keep the urgent channel reserved for genuine paging situations.

Using the same bot for everything. One bot for production alerts, and also for agency client alerts, and also for personal homelab alerts. A token compromise is then a much larger problem. Where there is no strong reason to share, separate bots keep the blast radius small.

No backup notification channel. Telegram is reliable but not infallible — the service has had outages, and individual devices lose connectivity. A critical alert routed only to Telegram disappears silently when Telegram is not reachable. Pairing Telegram with email for critical alerts is a very cheap belt-and-braces insurance policy.

Alerts muted by "do not disturb". Most phones apply do-not-disturb rules overnight. Telegram respects these by default — which is exactly what you do NOT want for a genuinely critical production alert. On iOS and Android alike, configure the Telegram group as an exception to do-not-disturb, or mark specific chats as "priority" so overnight alerts actually break through. Without this, the silent-message feature becomes accidentally universal.

Forgetting that everyone in the group sees alerts. If sensitive monitoring context appears in alert messages — internal hostnames, API keys in failure logs — everyone in the group sees it. Keep alert content suitable for the audience of the group. For genuinely sensitive content, use a private channel or a paging tool with better access controls.

Summary

Telegram notifications in Uptime Kuma are easy to set up, free to run, and surprisingly well-suited to the mobile-first alerting niche. The bot-creation flow takes five minutes via BotFather; finding chat IDs takes another couple of minutes once; configuring Uptime Kuma is as simple as pasting the token and chat ID into the notification channel form. The silent-messages feature makes Telegram usefully flexible for mixed-severity alerting, and group chats scale the model from one-person homelabs to team and agency setups.

Telegram is not a replacement for email or for team chat platforms in a full organisational alerting stack. It is a useful addition — particularly for mobile, out-of-hours, or agency-style multi-client monitoring. Know when it is the right tool and when it is not, and it will pay for its setup time many times over.

A final observation from UK teams using Telegram for monitoring: the discipline that makes it work is the same discipline that makes any channel work — careful routing, sensible retries, and a willingness to prune alerts that are not earning their keep. The medium does not change the rules, just the clientele you can reach with it.

Frequently asked questions