概述

Telegram 通知媒介透過官方提供的 Bot API 把告警推送到 Telegram 的群組、頻道或私聊。訊息以 HTML 格式渲染，支援 <b> / <code> / <a> 等基本標籤。

• 適用情境：海外團隊，或希望透過行動端 IM 即時看到告警。
• 你需要準備：
  1. 一個 Telegram 帳號，以及能存取 Telegram 的網路環境（在中國大陸部署夜鶯需要設定代理伺服器）；
  2. 透過 @BotFather 建立一個 Bot，取得 Bot Token；
  3. 目標對話的 Chat ID（群組、頻道或私聊皆可）。
• 整個設定分三步：①建立 Bot 並取得 Token → ②取得目標對話的 Chat ID → ③在夜鶯新建 Telegram 通知媒介，並在通知規則裡填入 Token 和 Chat ID。

第一步：建立 Bot 並取得 Token

1. 在 Telegram 裡搜尋並開啟官方帳號 @BotFather，點擊 Start。

2. 輸入 /newbot，依提示依序輸入：

   • 機器人顯示名稱，例如 夜鶯告警；
   • 機器人 username（必須以 bot 結尾），例如 my_n9e_alert_bot。

3. 建立成功後，@BotFather 會發一條包含 HTTP API token 的訊息，格式如：

   123456789:AAEXXXX_yyyyZZZZZ-aaaBbbCccDdd
   

   這整串就是後面在夜鶯裡要填的 Token，請妥善儲存——若洩漏，等於別人能任意借你的 Bot 發送訊息。

第二步：取得目標對話的 Chat ID

Telegram Bot 不能主動加入群組／加好友，必須先讓它收到一條訊息，然後透過 API 反查。請依要推送的目標類型，依下列步驟操作：

情境 A：推送到私聊

1. 在 Telegram 裡搜尋你剛建立的 Bot（例如 @my_n9e_alert_bot），發一條 /start 給它。

2. 用瀏覽器開啟：

   https://api.telegram.org/bot<你的Token>/getUpdates
   

3. 在回傳的 JSON 中找到 "chat":{"id":123456789,"type":"private"...}，其中的 123456789 就是你的私聊 Chat ID（個人 Chat ID 一般是正整數）。

情境 B：推送到群組

1. 把 Bot 拉進目標群組，然後在群組裡發一句 @你的Bot hello（任何 @ 到 Bot 的訊息都可以）。
2. 存取上述同樣的 getUpdates 介面。
3. 找到 "chat":{"id":-1001234567890,"type":"supergroup"...} —— 群組的 Chat ID 是負數（以 -100 開頭的超級群組／一般群組以 - 開頭）。

情境 C：推送到頻道

1. 將 Bot 加入頻道並設為管理員，並授予「發布訊息」權限。
2. 在頻道裡隨意發一條訊息（必須是 Bot 已成為管理員之後的訊息）。
3. 同樣存取 getUpdates，找到 "chat":{"id":-1001234567890,"type":"channel"...} —— 頻道 Chat ID 同樣是負數。

簡化做法：可以將 @getidsbot 或 @userinfobot 加到群組／頻道裡，它們會直接告訴你 Chat ID，不必手動呼叫 API。

第三步：在夜鶯新建 Telegram 通知媒介

1. 登入夜鶯 → 左側選單 通知 → 通知媒介。

2. 在左側媒介類型面板中點擊 Telegram，進入新建頁（對應 URL /notification-channels/add?ident=telegram）。

3. 填寫基礎資訊並儲存，絕大多數欄位系統已經預先填好：

   

   區塊	欄位	是否需要修改	說明
   基礎設定	名稱	需要	例如 Telegram Bot
   變數設定	參數設定	保持預設，不要刪除	已預先設定 token、chat_id、bot_name 三個參數
   HTTP 設定	URL	保持預設	https://api.telegram.org/bot{{$params.token}}/sendMessage
   HTTP 設定	請求方法	POST
   HTTP 設定	代理伺服器	依需求填寫	若夜鶯伺服器無法直連 api.telegram.org（多數中國大陸雲主機都不行），請在這裡填寫 HTTP 代理位址，例如 http://proxy.internal:3128
   HTTP 設定	請求參數 chat_id	保持預設	{{$params.chat_id}}

4. 繼續往下可以看到「請求內容」：

   

   預設請求內容：

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

   • {{$tpl.content}} 來自於「訊息範本」中的 Telegram 範本（系統內建）；
   • parse_mode: HTML 表示內文以 HTML 解析，可以使用 <b>、<i>、<code>、<a href> 等標籤；
   • 如果你的訊息範本使用 Telegram 風格的 Markdown，請將 parse_mode 改成 MarkdownV2。

5. 點擊 儲存。

說明：夜鶯 v8 已不再像舊版那樣把 Token / Chat ID 存在媒介本身，同一個 Telegram 媒介可以被多個 Bot ＋多個對話重複使用。

第四步：在通知規則裡填入 Token 和 Chat ID

1. 左側選單 通知 → 通知規則 → 新增（或編輯既有規則）。

2. 在「通知設定」區塊：

   • 通知媒介：選擇你剛剛建立的 Telegram 媒介；
   • 訊息範本：選擇 Telegram（系統內建，若沒有，請到「訊息範本」裡匯入預設範本）；
   • Token：貼上第一步從 @BotFather 取得的 Token；
   • Chat Id：貼上第二步取得的對話 ID（私聊正數／群組與頻道負數，直接填寫數字，前面有 - 就一起帶上）；
   • Bot Name：選填，方便自己辨識；
   • 適用級別 / 適用時段 / 適用標籤：依需求過濾。

3. 儲存後，點擊「通知測試」——Bot 應該立刻在對應對話裡發送一條 HTML 告警訊息。

一個媒介 + 多個 Bot ／多個群組

如果不同業務線希望推送到不同群組，不需要新建媒介，只要在「通知規則」裡新增一條規則、填入不同的 token + chat_id 即可。

常見問題

Q1：回傳 {"ok":false,"error_code":401,"description":"Unauthorized"}？

A：Token 填錯了，或者 Bot 已被 @BotFather 刪除／重設。請到 @BotFather 用 /mybots 找到 Bot → API Token 重新複製。

Q2：回傳 {"ok":false,"error_code":400,"description":"chat not found"}？

A：Chat ID 填錯了，或 Bot 還沒加入該對話／沒收到過對應對話的訊息。解決方式：

• 群組和頻道的 Chat ID 一定是負數，不要漏掉前面的 -；
• 讓 Bot 先加入群組／頻道，再用 getUpdates 重新查一次 ID。

Q3：在中國大陸部署夜鶯，連不上 api.telegram.org？

A：Telegram 在中國大陸被封鎖，必須設定代理伺服器。通知媒介表單裡的 代理伺服器 欄位請填 HTTP/HTTPS 代理位址（例如 http://127.0.0.1:7890）。若你的代理只支援 SOCKS5，需要先用工具轉成 HTTP 代理。

Q4：訊息在群組裡顯示的不是 HTML 格式，而是帶 <b> 原樣標籤？

A：請求內容裡的 parse_mode 必須與範本內容相符：HTML 內容用 HTML，Markdown 內容用 MarkdownV2。兩者不能混用，否則 Telegram 會回報 Can't parse entities。

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

A：使用 MarkdownV2 時，Telegram 要求所有特殊字元必須跳脫。建議直接用 HTML 模式，範本裡只用基本的 <b>、<code>、<a href=xxx> 就足夠了。

Q6：Bot 被限流（回傳 429 Too Many Requests）？

A：Telegram 官方對機器人限流大約為 每個 chat 1 條/秒、整體 30 條/秒。告警量大時：

• 在通知規則裡啟用告警收斂；
• 將告警分散到多個對話；
• 只把高優先級告警發到 Telegram。

參考資料

• Telegram Bot API 官方文件
• Telegram · 建立 Bot 指引
• Telegram · HTML 與 Markdown 格式說明