通知渠道与投递 - MoleSignal Docs

MoleSignal 将服务商凭证、接收人和路由规则分开管理。连接器只需配置一次，再把用户身份或兜底目标绑定到连接器，并通过通知策略决定何时使用这些路由。

资源	用途
连接器	保存组织级服务商凭证和传输配置。
用户通知	绑定各平台身份，并排列个人投递端点。
通知策略	匹配事件、解析接收人、选择模板并控制升级。
通知模板	复用纯文本、Markdown 或 HTML 消息正文。
兜底路由	在个人投递失败后，定义有序的团队和组织目标。
投递记录	查看投递尝试、耗时、错误、重试、确认与升级。

支持的连接器

连接器	配置	支持的目标
Email SMTP（`email_smtp`）	SMTP 主机、端口、凭证、发件地址、TLS 模式、超时	用户邮箱或固定邮箱
Slack App（`slack_app`）	Bot Token、App-Level Token、Client ID 与 Client Secret、Slack API 基础地址、超时	Slack 用户 ID 或频道 ID
Slack Webhook（`slack_webhook`）	Incoming Webhook 地址、超时	已配置 Webhook 或按目标覆盖的 Webhook 地址
飞书 App（`lark_app`）	App ID、App Secret、API 基础地址、接收人 ID 类型、超时	用户身份、邮箱或群聊 ID
飞书 Webhook（`lark_webhook`）	自定义机器人 Webhook 地址、可选签名密钥、超时	已配置 Webhook 或按目标覆盖的 Webhook 地址
钉钉 App（`dingtalk_app`）	Client ID 与 Client Secret、可选机器人 RobotCode、API 基础地址、超时	钉钉 userId 或 `openConversationId`
钉钉 Webhook（`dingtalk_webhook`）	自定义机器人 Webhook 地址、可选签名密钥、超时	已配置 Webhook 或按目标覆盖的 Webhook 地址
企业微信 App（`wecom_app`）	企业 ID、应用 Secret、AgentId、API 基础地址、超时	成员 UserID 或应用群聊 chatid
企业微信 Webhook（`wecom_webhook`）	群机器人 Webhook 地址、超时	已配置 Webhook 或按目标覆盖的 Webhook 地址
企业微信智能机器人（`wecom_bot`）	Bot ID、长连接 Secret、长连接地址	不发通知，只用于在 IM 里问 Mole Agent
Microsoft Teams 机器人（`teams_app`）	应用 ID、客户端密码、租户 ID、服务地址、超时	用户 ID 或会话 ID
Microsoft Teams Webhook（`teams_webhook`）	频道 Webhook 地址、超时	已配置 Webhook 或按目标覆盖的 Webhook 地址
Google Chat App（`google_chat_app`）	服务账号密钥（JSON）、可选 Pub/Sub 订阅、API 基础地址、超时	用户（`users/…`）或空间（`spaces/…`）
Google Chat Webhook（`google_chat_webhook`）	空间 Webhook 地址、超时	已配置 Webhook 或按目标覆盖的 Webhook 地址
阿里云语音通知（`aliyun_voice`）	AccessKey、文本转语音模板编号、可选外显号码、标题与正文变量、变量字数上限、播放遍数、API 基础地址、超时	内地号码
阿里云短信（`aliyun_sms`）	AccessKey、短信签名、模板编号、标题与正文变量、变量字数上限、API 基础地址、超时	内地号码或国际号码
Twilio 电话（`twilio_voice`）	Account SID、Auth Token、主叫号码、语言、可选声音、播放遍数、API 基础地址、超时	E.164 号码
Twilio 短信（`twilio_sms`）	Account SID、Auth Token、发送方、API 基础地址、超时	E.164 号码
AWS 语音（`aws_voice`）	区域、认证方式、发送方身份、可选 Polly 声音、播放遍数、可选 API 地址、超时	E.164 号码
AWS 短信（`aws_sms`）	区域、认证方式、可选发送方身份、可选 API 地址、超时	E.164 号码
通用 Webhook（`webhook`）	默认地址、HTTP 方法、请求头、超时	用户、地址、群组或按目标指定的 Webhook 地址

所有连接器的超时必须在 1 到 60 秒之间。URL 必须是绝对 http 或 https 地址。

创建并测试连接器

查看连接器需要 alerts.read；创建、编辑、测试、启停或删除连接器需要 alerts.manage。

打开通知设置

前往设置 → 通知 → 连接器。

选择服务商

点击新建连接器，填写唯一名称并选择连接器类型。连接器创建后不能更改类型。

填写服务配置

按下文填写凭证和传输参数。除非准备稍后再启用，否则保持允许此连接器投递开启。

保存连接器

点击保存连接器。MoleSignal 会加密保存完整配置，API 响应会把敏感值替换为 ***。

发送测试

编辑已保存的连接器，选择兼容的目标类型，输入真实目标，再点击测试连接。最近一次测试会把连接器状态更新为已连接或异常。

新连接器必须先保存才能测试。编辑连接器时，不要改动已掩码的 ***，系统会保留原有密钥。

配置各服务商

Email SMTP

填写 SMTP 主机、端口、按需填写用户名、密码，以及有效的发件地址。按邮件服务器选择 TLS 模式：

TLS 模式	适用场景
`none`	SMTP 连接不使用 TLS。不要在不可信网络上使用。
`starttls`	先连接再升级到 STARTTLS，常用端口为 `587`。
`tls`	从连接开始就使用 TLS，常用端口为 `465`。

测试时选择 fixed_address 或 direct_user，并输入 [email protected] 这类有效邮箱。

Slack App

创建能调用 chat.postMessage 的 Slack App 和 Bot Token，并把机器人加入需要接收通知的频道。填写：

Bot Token —— 通常以 xoxb- 开头；
App-Level Token —— 可选；以 xapp- 开头、带 connections:write 范围的令牌，填了之后 Mole Agent 可以通过 Socket Mode 在 Slack 里回答，见在 IM 里使用 Mole Agent；
API 基础地址 —— 除非使用兼容代理，否则保留 https://slack.com/api；
Client ID 与 Client Secret —— 见 Slack App 的 Basic Information，供状态页访客把页面添加到自己的 Slack 频道，见状态页；
超时 —— 1 到 60 秒。

连接器至少需要 Bot Token，或 Client ID 与 Client Secret，也可以三项都填。发送通知需要 Bot Token。Client Secret 与 Bot Token 一样随连接器加密保存，接口不会返回明文。 direct_user 目标填写 Slack 成员 ID，fixed_group 目标填写频道 ID。目标不能包含空格；#alerts 这类显示名称不是频道 ID。在 Mole Agent → 设置 → IM 接入里开启这个连接器后，经它发出的告警通知带确认、解决按钮，见告警卡片。

Slack Webhook

在 Slack 创建 Incoming Webhook，并把地址填入 Webhook 地址。fixed_group 目标使用连接器中配置的地址；webhook 目标会把目标值作为本次投递的替代地址。 MoleSignal 发送包含 text 字段的 JSON。任何非 2xx 响应都会将本次投递标记为失败。

飞书 App

创建能够获取 tenant access token 并发送消息的企业自建应用，填写 App ID 和 App Secret。除非使用其他兼容的飞书端点，否则保留默认 API 基础地址。所选接收人 ID 类型只用于 direct_user：

目标类型	目标值
`direct_user`	按接收人 ID 类型填写 `open_id`、`user_id`、`union_id` 或邮箱
`fixed_address`	邮箱；MoleSignal 使用 `receive_id_type=email` 发送
`fixed_group`	飞书群聊 ID；MoleSignal 使用 `receive_id_type=chat_id` 发送

应用用长连接接收事件后，Mole Agent 也能在飞书里回答，见在 IM 里使用 Mole Agent。在 Mole Agent → 设置 → IM 接入里开启这个连接器后，经它发出的告警通知带确认、解决按钮，见告警卡片。

飞书 Webhook

把自定义机器人地址填入 Webhook 地址。如果机器人启用了签名校验，再填写签名密钥。MoleSignal 会为每次请求生成时间戳和 HMAC-SHA256 签名。 fixed_group 目标使用已配置地址，webhook 目标可以用另一个绝对 URL 覆盖。请求体与签名格式见 Webhook 连接器。

钉钉 App

使用钉钉企业内部应用的机器人。填写应用的 Client ID 和 Client Secret。机器人没有单独的 RobotCode 时，机器人 RobotCode 留空，此时就是 Client ID。MoleSignal 用凭证换取访问令牌，再通过机器人发送 Markdown 消息。

目标类型	目标值
`direct_user`	应用可见范围内成员的钉钉 userId
`fixed_group`	机器人所在群的 `openConversationId`

机器人的消息用 Stream 模式接收后，Mole Agent 也能在钉钉里回答，见在 IM 里使用 Mole Agent。

钉钉 Webhook

把自定义机器人的地址填入 Webhook 地址。机器人开启了加签时，再填写签名密钥：MoleSignal 会为每次请求加上时间戳和 HMAC-SHA256 签名。fixed_group 目标使用已配置地址，webhook 目标会替换它。

企业微信 App

使用企业微信自建应用。填写企业 ID、应用的 Secret 和 AgentId。MoleSignal 用它们换取访问令牌，再发送 Markdown 消息，企业微信会在 4096 字节处截断。请把 MoleSignal 的出口地址加到应用的企业可信 IP。

目标类型	目标值
`direct_user`	应用可见范围内成员的 UserID
`fixed_group`	应用创建的群聊 chatid

企业微信 Webhook

把群机器人的地址填入 Webhook 地址。fixed_group 目标使用它，webhook 目标会替换它。

企业微信智能机器人

企业微信的智能机器人（API 模式，用长连接接收消息）。填写机器人的 Bot ID 和长连接专用的 长连接 Secret；除非企业微信另给了地址，否则保留默认的长连接地址。这个连接器不发通知，也不能在通知策略或个人的接收顺序里选它：它只让 Mole Agent 在企业微信里回答，见在 IM 里使用 Mole Agent。发通知请用企业微信 App 或企业微信 Webhook 连接器。成员在这个连接器上的通知方式是机器人看到的 userid，只用来认出 IM 里提问的人。

Microsoft Teams 机器人

使用 Bot Framework 机器人。填写应用 ID、客户端密码和租户 ID；较早的多租户机器人，租户填 botframework.com。除非机器人运行在区域云或主权云，否则保留默认服务地址。机器人要先安装给要接收消息的人和团队。

目标类型	目标值
`direct_user`	Teams 用户 ID（`29:…`）或此人的 Microsoft Entra 对象 ID
`fixed_group`	频道或群聊的会话 ID（`19:…`）

把 MoleSignal 给出的回调地址填到 Azure Bot 的 Messaging endpoint 后，Mole Agent 也能在 Teams 里回答，见在 IM 里使用 Mole Agent。

Microsoft Teams Webhook

用 Workflows 流程（收到 Webhook 请求时发布到频道）创建频道 Webhook，或使用旧版 Incoming Webhook，把地址填入 Webhook 地址。MoleSignal 以 Adaptive Card 发送每条消息。

Google Chat App

使用 Chat 应用的服务账号。把服务账号的 JSON 密钥粘贴到服务账号密钥；它随连接器加密保存，接口不会返回。MoleSignal 用这个密钥签名换取令牌，以应用的身份发送消息。

目标类型	目标值
`direct_user`	给应用发过消息或装了应用的用户（`users/123…`）
`fixed_group`	应用所在的空间（`spaces/AAAA…`）

填了 Pub/Sub 订阅（projects/<项目>/subscriptions/<订阅>）后，Mole Agent 也能在 Google Chat 里回答，见在 IM 里使用 Mole Agent。只发通知时不用填。

Google Chat Webhook

把空间的 Incoming Webhook 地址填入 Webhook 地址。fixed_group 目标使用它，webhook 目标会替换它。

电话与短信的号码

电话与短信连接器发给一个号码：成员绑定的手机号（direct_user），或兜底路由里的固定号码（fixed_address）。号码以 + 和国家码开头，例如 +8613800138000，空格和短横线会被去掉；阿里云连接器也认 11 位内地手机号。电话先念通知的标题，再念正文，最多 400 字；短信是标题一行、正文一行，最多 320 字。阿里云只发审核过的模板，标题与正文填进模板变量，见下文。服务商会限制同一号码被拨打、接收短信的频率。因为超限、号码有误或模板没通过而被拒时，这次投递失败，通知策略接着尝试此人的下一个通知方式和兜底路由。电话是否接通、有没有人听完不会回传：投递成功只表示服务商已经受理这通电话或这条短信。同一个连接器给同一个号码一分钟只拨一次。一分钟内再来的通知排在这条线路上，投递记录显示排队合并；一分钟到了合并成一通电话，依次念各条通知的标题，排队期间已被确认的不再拨。阿里云对同一号码本来就是每分钟一通，合并之后不会因为告警密集而被拒。

阿里云语音通知

使用阿里云语音服务的语音通知，只能拨内地号码。先在语音服务控制台完成企业资质，申请文本转语音的语音通知模板，例如 您好，${content}，请尽快处理。，再为一个 RAM 用户创建只能调用语音服务的 AccessKey。填写：

AccessKey ID 与 AccessKey Secret；
模板编号 —— 以 TTS_ 开头；
外显号码 —— 空着是公共模式；填专属模式里购买的号码时，来电显示这个固定号码，值班人可以把它存成联系人。模板的模式要与之一致；
标题变量 与 正文变量 —— 模板里的变量名，例如 content。标题、正文按变量字数上限（默认 35）截断后填入；模板没有变量时两项都留空；
播放遍数 —— 1 到 3 遍。

阿里云对同一号码每分钟最多拨 1 次、每小时 5 次、每天 20 次，超出的呼叫会被拒绝。变量里不要放网址或 IP。

阿里云短信

在短信服务控制台申请短信签名和通知类模板，例如 ${content}，请尽快处理。，再填写 AccessKey、短信签名、模板编号（以 SMS_ 开头）以及标题变量与正文变量。通知类模板的每个变量默认最多 35 个字；企业用户向阿里云申请放宽后，可以调大变量字数上限。变量里不能放网址或 IP。号码可以是内地手机号，也可以是国际号码。

Twilio 电话

在 Twilio 控制台找到 Account SID 与 Auth Token，再填写：

主叫号码 —— 账号里能打电话的号码，例如 +14155550100；
语言 —— 念通知用的语言，例如 en-US、cmn-CN；
声音 —— 可选，例如 Polly.Joanna、Polly.Zhiyu，空着用 Twilio 的默认声音；
播放遍数 —— 1 到 3 遍。

Twilio 短信

填写 Account SID、Auth Token 和发送方。发送方可以是账号里的号码（E.164）、Messaging Service（MG 开头），或不超过 11 个字母和数字的字母发送方 ID（只在支持它的国家可用）。发往美国号码前，要先完成 A2P 10DLC 注册。

AWS 语音与短信

AWS 语音（aws_voice）用 AWS End User Messaging 的 SendVoiceMessage 拨号，由 Amazon Polly 念通知；AWS 短信（aws_sms）用 SendTextMessage 发事务类短信。填写：

区域 —— 例如 us-east-1；
认证方式 —— 与数据接入的 AWS 连接器相同：访问密钥、临时密钥、节点身份、扮演角色或 Web Identity。扮演角色时，在角色的信任策略里要求页面给出的外部 ID；
发送方身份 —— 号码、号码 ID、号码池 ID 或它们的 ARN。语音必填，而且号码要能打电话；短信可以不填，由 AWS 按目的地选号码，也可以填发送方 ID；
Polly 声音 —— 仅语音，可选，空着是 MATTHEW，中文用 ZHIYU；
API 地址 —— 可选，空着就是所在区域的端点。

所用身份需要 sms-voice:SendVoiceMessage 或 sms-voice:SendTextMessage 权限。还在沙盒里的 AWS 账号只能发给验证过的号码。

通用 Webhook

填写默认地址，并选择 POST、PUT 或 PATCH。请求头使用 JSON 对象：

{
  "Authorization": "Bearer <token>",
  "X-Environment": "production"
}

MoleSignal 发送以下 JSON：

{
  "target": {
    "type": "fixed_group",
    "value": "platform-oncall",
    "metadata": {}
  },
  "message": {
    "title": "Checkout error rate is high",
    "text": "The error rate exceeded 5%.",
    "markdown": "**Checkout** error rate exceeded 5%.",
    "html": null,
    "metadata": {}
  }
}

direct_user、fixed_address 和 fixed_group 会请求已配置的默认地址，并把目标作为路由数据放入请求体。webhook 会用目标值替换默认地址。2xx 响应表示成功；响应包含 X-Request-ID 时，MoleSignal 会把 Header 值记录为服务商消息 ID。

Webhook 地址、Authorization Header、Token、密码和签名密钥都属于凭证。不要把凭证值写入测试目标、通知模板或事件属性。

绑定用户通知方式

管理员可以打开设置 → 通知 → 用户通知，选择成员，再点击绑定通知方式。每个通知身份会选择一个连接器和一个外部身份，例如邮箱、Slack 用户 ID、飞书用户 ID，或电话与短信连接器用的手机号。绑定后按以下步骤配置：

发送测试，确认服务商接受该身份；
组织确认归属后，将身份标记为已验证；
在告警事件、值班通知或报告偏好中启用该身份；
有多个身份时，按主用到备用的顺序排列；
按需配置免打扰时段，并决定严重告警能否绕过免打扰。

没人确认就换下一种方式

告警事件的接收顺序里，第二步起可以填等待的分钟数：

设置	效果
第一步	告警触发或升级到此人时立即发送。
等待 N 分钟	从第一次通知此人算起，N 分钟后仍没人确认告警，就用这一步再发一次。
与上一步相同的分钟数	只在上一步发送失败时使用。

例如飞书（立即）、短信（3 分钟后）、电话（5 分钟后）：告警被确认或解决后，后面的步骤都不再发，这个告警各次升级发给其他人的也一样。发送失败的一步照旧立即换下一步。等待时间最长一天，只对告警事件生效；值班通知和报告的接收顺序只做失败兜底。成员可以在账号设置 → 通知设置中管理个人身份和偏好。读取其他成员设置需要 org.members.read，修改或确认其他成员身份需要 org.members.manage。

删除通知身份前，先从所有投递偏好中移除该身份。

创建模板和策略

打开设置 → 通知 → 通知模板，创建可复用的纯文本、Markdown 或 HTML 正文。选择通知类别，插入支持的占位符，再使用预览属性检查渲染结果。然后打开通知策略并创建路由规则：

选择事件类型和通知类别；
添加 JSON 匹配条件并设置策略优先级；
选择接收人解析器和解析器配置；
选择尊重用户偏好、强制一个连接器或通过多个连接器发送；
选择模板，并启用用户、团队或组织兜底；
按需设置确认超时和升级路由；
检查实时投递预览；预览会解析真实用户和路由，但不会发送消息。

策略当前覆盖告警生命周期和值班排班事件。策略编辑器会列出运行中后端支持的事件类型和接收人解析器。

配置兜底路由

打开设置 → 通知 → 兜底路由。选择组织或团队范围，再选择通知类别。添加一个或多个已启用的连接器，选择 fixed_address 或 fixed_group，并填写服务商目标。已启用的个人路由阶段失败后，MoleSignal 会按页面显示顺序尝试兜底路由。通知策略决定是否启用用户、团队和组织兜底。

查看和重试投递

打开设置 → 通知 → 投递记录，按事件 ID、状态或阶段筛选。选择一条记录，可以查看脱敏目标、连接器、耗时、服务商错误和完整投递链路。

alerts.read 可以查看投递历史；
alerts.acknowledge 可以确认来源事件；
alerts.manage 可以重试失败路由。

重试会创建新的投递尝试，不会修改已有历史。阶段为 直接发送 的投递来自自行指定连接器和目标的功能，例如定时日志巡检。直接发送不经过通知策略，也不能重试。

连接器生命周期与状态

状态	含义
未知	连接器还没有完成过成功或失败的测试。
已连接	最近一次测试成功。
异常	最近一次测试失败；后续测试成功前，正常路由会跳过该连接器。
已停用	MoleSignal 不会通过该连接器测试或投递。

停用连接器不会删除引用。用户身份、通知策略、兜底路由或定时日志巡检仍引用连接器时，不能删除连接器。先迁移这些引用，再删除连接器。

排查投递问题

现象	检查项
SMTP 身份验证或 TLS 失败	检查主机、端口、凭证、TLS 模式、发件地址、DNS 和出向网络。
Slack 返回 API 错误	检查 Bot Token、`chat.postMessage` 权限、目标 ID 和频道成员关系。
飞书拒绝消息	检查应用权限、接收人 ID 类型、群聊成员关系、Webhook 密钥和服务器时间。
Webhook 返回错误	检查 URL、方法、Header JSON、超时，以及对端是否返回 2xx。
用户没有收到通知	检查身份和连接器是否启用、类别偏好是否包含该身份，以及免打扰是否生效。
兜底路由没有执行	检查策略是否启用该层兜底，以及对应类别是否存在已启用路由。
电话或短信没有发出	检查号码是否以 + 和国家码开头、模板与签名是否已审核、模板变量名是否一致，以及服务商的频率限制和账号沙盒。

告警

创建规则并处理告警事件生命周期。

Webhook 连接器

查看 Webhook 请求体、目标覆盖、签名与安全要求。

​支持的连接器

​创建并测试连接器

​配置各服务商

​Email SMTP

​Slack App

​Slack Webhook

​飞书 App

​飞书 Webhook

​钉钉 App

​钉钉 Webhook

​企业微信 App

​企业微信 Webhook

​企业微信智能机器人

​Microsoft Teams 机器人

​Microsoft Teams Webhook

​Google Chat App

​Google Chat Webhook

​电话与短信的号码

​阿里云语音通知

​阿里云短信

​Twilio 电话

​Twilio 短信

​AWS 语音与短信

​通用 Webhook

​绑定用户通知方式

​没人确认就换下一种方式

​创建模板和策略

​配置兜底路由

​查看和重试投递

​连接器生命周期与状态

​排查投递问题

告警

Webhook 连接器

支持的连接器

创建并测试连接器

配置各服务商

Email SMTP

Slack App

Slack Webhook

飞书 App

飞书 Webhook

钉钉 App

钉钉 Webhook

企业微信 App

企业微信 Webhook

企业微信智能机器人

Microsoft Teams 机器人

Microsoft Teams Webhook

Google Chat App

Google Chat Webhook

电话与短信的号码

阿里云语音通知

阿里云短信

Twilio 电话

Twilio 短信

AWS 语音与短信

通用 Webhook

绑定用户通知方式

没人确认就换下一种方式

创建模板和策略

配置兜底路由

查看和重试投递

连接器生命周期与状态

排查投递问题