Overview

The Telegram notification channel uses the official Bot API to push alerts to a Telegram group, channel, or private chat. Messages are rendered as HTML and support basic tags such as <b>, <code>, and <a>.

• Use case: overseas teams, or anyone who wants to see alerts on a mobile IM in real time.
• Prerequisites:
  1. A Telegram account & a network environment that can reach Telegram (Nightingale deployed inside mainland China requires a proxy);
  2. A Bot created via @BotFather, plus its Bot Token;
  3. The Chat ID of the target conversation (group, channel, or private chat all work).
• The whole setup has three steps: ① Create a Bot and get a Token → ② Get the target conversation’s Chat ID → ③ Create a Telegram notification channel in Nightingale, then fill in the Token and Chat ID inside a notification rule.

Step 1: Create a Bot and get the Token

1. Open the official account @BotFather in Telegram and click Start.

2. Send /newbot, then follow the prompts to enter:

   • the bot’s display name, e.g. Nightingale Alert;
   • the bot’s username (must end with bot), e.g. my_n9e_alert_bot.

3. Once created, @BotFather sends a message containing the HTTP API token, like:

   123456789:AAEXXXX_yyyyZZZZZ-aaaBbbCccDdd
   

   This whole string is the Token you’ll fill into Nightingale later — keep it safe; if leaked, anyone can send messages on behalf of your Bot.

Step 2: Get the target conversation’s Chat ID

A Telegram Bot cannot proactively join groups or add friends — it must first receive a message, then you reverse-look-up via the API. Depending on the target type, follow the steps below:

Scenario A: push to a private chat

1. Search for the Bot you just created in Telegram (e.g. @my_n9e_alert_bot) and send it /start.

2. Open this URL in a browser:

   https://api.telegram.org/bot<your-token>/getUpdates
   

3. In the returned JSON find "chat":{"id":123456789,"type":"private"...}. The 123456789 is your private-chat Chat ID (private Chat IDs are typically positive integers).

Scenario B: push to a group

1. Add the Bot into the target group, then send a message such as @your_bot hello (any message that @-mentions the Bot works).
2. Visit the same getUpdates endpoint as above.
3. Find "chat":{"id":-1001234567890,"type":"supergroup"...} — group Chat IDs are negative numbers (supergroups start with -100; regular groups start with -).

Scenario C: push to a channel

1. Add the Bot as an admin of the channel and grant it the “Post Messages” permission.
2. Post any message in the channel (it must be sent after the Bot became an admin).
3. Again visit getUpdates and find "chat":{"id":-1001234567890,"type":"channel"...} — channel Chat IDs are also negative.

Shortcut: add @getidsbot or @userinfobot to the group/channel — they will tell you the Chat ID directly, no manual API calls needed.

Step 3: Create a Telegram notification channel in Nightingale

1. Sign in to Nightingale → left menu Notification → Notification Channels.

2. In the channel-type panel on the left, click Telegram to enter the create page (URL /notification-channels/add?ident=telegram).

3. Fill in the basics and save. Most fields are pre-filled by the system:

   

   Section	Field	Edit needed	Notes
   Basic	Name	Yes	e.g. Telegram Bot
   Variables	Parameters	Keep default, do not delete	The parameters token, chat_id, bot_name are pre-set
   HTTP	URL	Keep default	https://api.telegram.org/bot{{$params.token}}/sendMessage
   HTTP	Method	POST
   HTTP	Proxy	As needed	If the Nightingale server cannot reach api.telegram.org directly (most cloud hosts inside mainland China cannot), fill in an HTTP proxy URL here, e.g. http://proxy.internal:3128
   HTTP	Request Parameter chat_id	Keep default	{{$params.chat_id}}

4. Scrolling down you will see “Request Body”:

   

   Default request body:

   {"text":"{{$tpl.content}}","parse_mode": "HTML"}
   

   • {{$tpl.content}} comes from the Telegram message template (built-in);
   • parse_mode: HTML means the body is parsed as HTML; you can use <b>, <i>, <code>, <a href> and similar tags;
   • If your message template uses Telegram-flavored Markdown, change parse_mode to MarkdownV2.

5. Click Save.

Note: Nightingale v8 no longer stores the Token/Chat ID on the channel itself like older versions did. The same Telegram channel can be reused across multiple Bots and multiple conversations.

Step 4: Fill in the Token and Chat ID in the notification rule

1. Left menu Notification → Notification Rules → New (or edit an existing rule).

2. In the “Notification Configuration” area:

   • Notification Channel: pick the Telegram channel you just created;
   • Message Template: pick Telegram (built-in; if missing, import the default templates from “Message Templates”);
   • Token: paste the Token from @BotFather in Step 1;
   • Chat Id: paste the Chat ID from Step 2 (positive for private chats, negative for groups and channels — keep the leading - if any);
   • Bot Name: optional, helpful for identifying the rule;
   • Applicable Severity / Time Range / Tags: filter as needed.

3. After saving, click “Notification Test” — the Bot should immediately send an HTML alert message to the corresponding conversation.

One channel + multiple Bots / multiple groups

If different business lines want to push to different groups, no new channel is needed — just create another notification rule with a different token + chat_id.

FAQ

Q1: Returning {"ok":false,"error_code":401,"description":"Unauthorized"}?

A: The Token is wrong, or the Bot has been deleted/reset by @BotFather. Go to @BotFather, run /mybots to find the Bot → API Token and copy it again.

Q2: Returning {"ok":false,"error_code":400,"description":"chat not found"}?

A: The Chat ID is wrong, or the Bot has not joined that conversation / has not received any message in it. Fixes:

• Group and channel Chat IDs are always negative — don’t drop the leading -;
• Make sure the Bot has joined the group/channel, then call getUpdates again to look up the ID.

Q3: Nightingale deployed inside mainland China cannot reach api.telegram.org?

A: Telegram is blocked in mainland China; a proxy is required. In the Proxy field of the notification channel form, fill in an HTTP/HTTPS proxy URL (e.g. http://127.0.0.1:7890). If your proxy only supports SOCKS5, you’ll need a tool to convert it into an HTTP proxy first.

Q4: Messages show raw <b> tags in the group instead of HTML formatting?

A: The parse_mode in the request body must match the template content: HTML content with HTML, Markdown content with MarkdownV2. They cannot be mixed; otherwise Telegram returns Can't parse entities.

Q5: Can't parse entities: Character '-' is reserved and must be escaped?

A: When using MarkdownV2, Telegram requires every special character to be escaped. The simpler approach is to stay in HTML mode and stick to basic tags like <b>, <code>, <a href=xxx>.

Q6: Bot getting throttled (returns 429 Too Many Requests)?

A: Telegram’s official limit for bots is roughly 1 message/sec per chat and 30 messages/sec network-wide. For high alert volume:

• Enable alert suppression in the notification rule;
• Spread alerts across multiple conversations;
• Send only high-priority alerts to Telegram.

References

• Telegram Bot API Official Documentation
• Telegram · Creating a New Bot
• Telegram · HTML and Markdown Formatting Options