Telegram

概述

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 格式说明