For the complete documentation index, see llms.txt. Markdown versions are available by appending .md to documentation URLs.

Telegram Alerts - Configure a Telegram Notification Channel

SigNoz Cloud - This page applies to SigNoz Cloud editions.
Self-Host - This page applies to self-hosted SigNoz editions.

Overview

A Telegram notification channel sends SigNoz alerts to a Telegram chat through a bot. SigNoz posts one message for each alert that fires. It also posts a message when the alert resolves. You can reuse the channel in any alert rule.

Prerequisites

Before you configure Telegram as a notification channel, you need:

  • Telegram account and chat: A group, or a topic in a forum group, that receives the alerts.
  • SigNoz version: v0.147.0 or later.
  • SigNoz permission: notification-channel:create, which the Admin role has.

Create a Telegram Channel

Step 1. Create a bot

  1. In Telegram, open a chat with @BotFather.
  2. Send /newbot and follow the prompts to choose a name and a username.
  3. Copy the bot token that BotFather returns. The token looks like 123456789:AA....

For the full bot setup, see Telegram: Building your first bot.

Step 2. Add the bot to the chat and get the chat ID

  1. Add the bot to the group that receives the alerts.

  2. In the group, send /start@<bot-username>. A bot in a group sees only commands that name it, so this message makes the chat visible to the bot.

  3. Open the following URL in a browser. Replace <bot-token> with the token from Step 1.

    https://api.telegram.org/bot<bot-token>/getUpdates
  4. In the response, find the message you sent. Copy the number in message.chat.id. The ID of a group is negative, for example -1001234567890.

To post into one topic of a forum group, also copy message.message_thread_id from a message you sent in that topic. The General topic has no thread ID, so leave the field empty for it.

Step 3. Create the notification channel in SigNoz

  1. Navigate to Alerts > Configuration > Notification Channels and click New Channel.
  2. In the General section, enter a Name and select Telegram as the Type. Leave Send resolved alerts on to also get a message when an alert stops firing.
  3. In the Connection section, paste the bot token into Bot token and the chat ID into Chat ID. For a forum topic, enter the topic ID in Message thread ID.
  4. In the Message section, keep the default Title and Message templates, or edit them as described in Customize the Message.
  5. Continue with Validate to test the channel and save it.
New channel form in SigNoz with the Type set to Telegram and the Bot token, Chat ID, and Message thread ID boxes in the Connection section.
Create a Telegram notification channel.

Validate

  1. On the channel form, click Test. SigNoz sends a test alert to the chat.
  2. Open the Telegram chat. A message that starts with [FIRING:1] Test Alert (test-receiver) appears within a few seconds.
  3. Click Save. The channel now appears in the list under Alerts > Configuration > Notification Channels.
Telegram message from the SigNoz bot with the title [FIRING:1] Test Alert (test-receiver) and the Alert, Summary, and Description lines.
The test alert as it appears in the Telegram chat.
  1. In an alert rule, select the Telegram channel. SigNoz then posts to the chat each time that rule fires and, with Send resolved alerts on, each time it resolves. The message shows the alert name, the severity, the summary and the description of the alert, and a View in SigNoz link.
Two Telegram messages from an alert rule, one with the title [FIRING:1] and one with the title [RESOLVED], each with a View in SigNoz link.
A firing alert and its resolved message in Telegram.

Customize the Message

The Title and Message boxes accept Go templates, so they can read values from the alert. SigNoz sends the Title in bold above the Message.

SigNoz always sends the message to Telegram as HTML. Use only the tags that Telegram supports, such as <b>, <i>, <code>, and <a href="...">. See Telegram: HTML style for the full list. In the Title and Message boxes, Markdown is not supported. Telegram shows **bold** as plain text.

Telegram rejects the whole message when it finds a tag it does not know, such as <value> or <h1>. Escape every <, >, and & that is not part of a tag or an entity: write &lt;, &gt;, and &amp;. For example, write latency &lt; 5s and &lt;value&gt;. To insert alert values safely, pipe them through the html function, as the default template does.

{{ range .Alerts -}}
<b>{{ .Labels.alertname | html }}</b> is {{ .Status }}
<i>{{ .Annotations.summary | html }}</i>
<a href="{{ .GeneratorURL | html }}">Open in SigNoz</a>
{{ end }}

Telegram allows at most 4096 characters in one message. SigNoz cuts off a longer message at that limit.

Message and Advanced sections of the SigNoz Telegram channel form with the Title, Message, Bot API URL, and Send silently fields.
The Message and Advanced sections of the Telegram channel form.

The Advanced section has two more options:

  • Send silently: Delivers the message without a notification sound.
  • Bot API URL: Sends the message to a self-hosted Telegram Bot API server. Leave it empty to use https://api.telegram.org.

Configure Programmatically

You can create the channel with the SigNoz API instead of the UI.

API Endpoint: POST /api/v2/notification_channels

curl -X POST "<your-signoz-url>/api/v2/notification_channels" \
  -H 'SIGNOZ-API-KEY: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "telegram-infra",
    "displayName": "Telegram Infra",
    "config": {
      "kind": "telegram",
      "spec": {
        "botToken": "<bot-token>",
        "chatId": <chat-id>
      }
    }
  }'

Verify these values:

  • <your-signoz-url>: The base URL of your SigNoz instance, for example https://<your-organization>.signoz.cloud.
  • <your-api-key>: An API key of a service account with the Admin role. See Service Accounts to create one.
  • <bot-token>: The token from Step 1, as a string.
  • <chat-id>: The chat ID from Step 2, as a number without quotes.

To post into a forum topic, add "messageThreadId": <topic-id> to spec. Write the topic ID as a number without quotes.

To test the settings without saving a channel, send the config object to POST /api/v2/notification_channels/test. The endpoint returns 204 when Telegram accepts the message.

Request body attributes:

FieldTypeDescription
namestringThe immutable channel identifier: lowercase letters, digits, and hyphens, at most 63 characters. Required unless generateName is true.
displayNamestringThe name that the UI shows and that alert rules select. Defaults to name. Required when generateName is true.
generateNamebooleanBuilds name from displayName plus a random suffix. name must then be empty. The default is false.
config.kindstringMust be telegram.
config.spec.botTokenstringThe bot token. Required.
config.spec.chatIdnumberThe numeric chat ID. Required. A string such as @mygroup is rejected.
config.spec.messageThreadIdnumberThe topic ID inside a forum group.
config.spec.titlestringGo template for the title.
config.spec.messagestringGo template for the message body.
config.spec.sendResolvedbooleanWhether to send a message when the alert resolves. The default is true.
config.spec.disableNotificationsbooleanSends the message without a notification sound.
config.spec.apiUrlstringThe URL of a self-hosted Bot API server.

The API rejects an unknown field in config.spec. For example, parseMode returns json: unknown field "parseMode", because the parse mode is always HTML.

Troubleshooting

getUpdates returns an empty result

Telegram keeps an update for at most 24 hours, and getUpdates does not work while the bot has a webhook. Send /start@<bot-username> in the group again, and reload the getUpdates URL right away. If the bot has a webhook, open https://api.telegram.org/bot<bot-token>/deleteWebhook first. If another service uses the bot through that webhook, create a separate bot for SigNoz instead.

Error: group chat was upgraded to a supergroup chat

Telegram changed the chat ID of the group, for example when you turned on Topics. Read the new ID from getUpdates and update Chat ID. The error response includes the new ID in migrate_to_chat_id.

Error: value of type 'string' was received for field 'chatId'

SigNoz accepts only the numeric chat ID. It does not accept @username. Use the ID from getUpdates.

Error: unexpected status code 401 ... Unauthorized

The bot token is wrong or revoked. Copy the token from @BotFather again.

Error: can't parse entities: Unsupported start tag "value"

The message contains text that looks like an HTML tag, and Telegram does not support that tag. Escape the text as &lt;value&gt;, or pipe the alert value through html in the template.

Error: is not authorized to perform notification-channel:create

Your user or API key does not have the notification-channel:create permission. Use an Admin account, or ask an Admin to grant the permission to your role.

The message arrives but View in SigNoz is plain text

On Self-Hosted SigNoz, the link needs the external URL of your instance. Set SIGNOZ_GLOBAL_EXTERNAL__URL to the URL that users open in the browser, for example https://signoz.example.com, and restart SigNoz. See Serving SigNoz on an External URL. The Test button never shows a link, because a test alert has no source URL.

Next Steps

Get Help

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack. If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.

Is this page helpful

Last updated—November 17, 2026