夜莺 v8 从 beta7 版本开始抽象出通知规则，beta8 之后钉钉通知支持更方便地 at 人。本文只讲钉钉 at 人的配置逻辑。
如果你还不了解新版通知规则或钉钉通知基础配置，建议先阅读：
- 新版通知规则介绍：夜莺监控巨大革新：抽象出通知规则，增强告警通知的灵活性
- 新版通知规则对接钉钉：夜莺监控 v8.0 新版通知规则 | 对接钉钉告警
核心要点
- 钉钉
text消息和markdown消息的 at 人逻辑不同。 - 夜莺告警通常使用钉钉 markdown 消息，因此需要同时满足两个条件：
at.atMobiles中有手机号，消息正文中也出现@手机号字符串。 - 夜莺 v8.0.0-beta.8 以上版本内置了
batchContactsAts和batchContactsJsonMarshal两个函数，用来把联系人手机号列表渲染成钉钉需要的格式。 - 推荐在 DingTalk 通知媒介的联系方式中选择
Phone，让通知规则中的联系人自动转成手机号列表，而不是把手机号写死在模板里。
先理解钉钉 text 消息怎么 at 人
钉钉的 text 消息体中，只要把手机号写到 atMobiles 里即可。下面用一条 curl 命令演示：
curl -X POST \
-H "Content-Type: application/json" \
-d '{
"msgtype": "text",
"text": {
"content": "这是 text 文本消息 at: 2025-03"
},
"at": {
"atMobiles": ["18612185520"],
"isAtAll": false
}
}' \
'https://oapi.dingtalk.com/robot/send?access_token=your_access_token'
这个例子里：
msgtype是text，表示发送普通文本消息。at.atMobiles是手机号数组，可以放一个或多个手机号。text.content是消息内容，不需要额外写@18612185520。- 示例内容中故意写了
2025-03，因为这个机器人使用关键字鉴权，关键字是20，消息中必须包含20这个字符串，否则消息会发送失败。
你可以把手机号换成自己的，把 your_access_token 换成自己的机器人 Token，然后执行命令观察效果。
再理解钉钉 markdown 消息怎么 at 人
实际告警消息中，钉钉告警一般会采用 markdown 消息。markdown 消息的请求体和 text 消息不同：
curl -X POST \
-H "Content-Type: application/json" \
-d '{
"msgtype": "markdown",
"markdown": {
"title": "测试标题",
"text": "#### 测试标题\n\n> 这是一条2025年的测试消息 \n\n@18612185520"
},
"at": {
"atMobiles": ["18612185520"],
"isAtAll": false
}
}' \
'https://oapi.dingtalk.com/robot/send?access_token=your_access_token'
markdown 类型消息要注意两点：
atMobiles和isAtAll两个字段仍然需要配置。- 如果想 at 某个人，只把手机号放到
atMobiles中不够，还要在markdown.text中显式写出@18612185520这样的字符串。
如果想 at 多个人，就在正文里写多个 @手机号，例如 @18612185520 @18612185521，同时在 atMobiles 数组中放入对应手机号。
夜莺里推荐怎么配置钉钉 at 人
理解了钉钉 markdown 的格式之后，再看夜莺里的配置就简单了。夜莺 v8.0.0-beta.8 以上版本有两种做法：
| 方案 | 配置方式 | 适用情况 | 问题 |
|---|---|---|---|
| 自定义参数变量 | 在 DingTalk 通知媒介的变量配置中定义 ats 等参数，让用户在通知规则中填写要 at 的手机号 |
快速验证模板逻辑 | 手机号容易写死，后续换人需要改通知规则 |
| 联系方式选择 Phone | 在 DingTalk 通知媒介的变量配置中，把联系方式选择为 Phone |
推荐方式，适合日常使用 | 需要联系人信息中有手机号 |
更推荐第二种方式。通知规则中选择联系人后，夜莺会根据联系方式拿到这些人的手机号，并把手机号列表交给模板渲染。
DingTalk 通知媒介请求体怎么写
钉钉 markdown 消息需要同时生成两部分：
- 正文里的
@手机号字符串。 at.atMobiles数组。
在 DingTalk 通知媒介最下面的请求体中写入：
{"msgtype": "markdown", "markdown": {"title": "{{$tpl.title}}", "text": "{{$tpl.content}}\n\n{{batchContactsAts $sendtos}}"}, "at": {"atMobiles": {{batchContactsJsonMarshal $sendtos}} }}
这个请求体中有三个关键变量和两个关键函数：
| 名称 | 类型 | 含义 |
|---|---|---|
$tpl.title |
模板变量 | 通知规则中钉钉消息模板渲染出的告警标题 |
$tpl.content |
模板变量 | 通知规则中钉钉消息模板渲染出的告警正文 |
$sendtos |
模板变量 | 通知规则中选中的一批联系方式；联系方式选择 Phone 时，它就是手机号列表 |
batchContactsAts |
模板函数 | 把手机号列表转换成 @18612185520 @18612185521 这种字符串 |
batchContactsJsonMarshal |
模板函数 | 把手机号列表转换成 ["18612185520", "18612185521"] 这种 JSON 字符串 |
这两个函数是夜莺 v8.0.0-beta.8 以上版本内置的，不需要额外开发，直接在模板里使用即可。
配置检查清单
配置完成后，按下面顺序排查最稳妥：
- 夜莺版本是否为 v8.0.0-beta.8 以上。
- DingTalk 通知媒介的联系方式是否选择了
Phone。 - 通知规则里是否选择了要通知的人。
- 被选择的联系人是否维护了手机号。
- 请求体中是否同时使用了
batchContactsAts $sendtos和batchContactsJsonMarshal $sendtos。 - 钉钉机器人是否通过了安全校验，例如关键字校验。
常见问题
Q1：为什么 atMobiles 里有手机号，但钉钉没有真正 at 人？
A：如果发送的是 markdown 消息，只写 atMobiles 不够，还需要在 markdown.text 中出现 @手机号 字符串。夜莺模板里用 batchContactsAts $sendtos 生成这部分内容。
Q2：为什么模板里不用手写手机号？
A：手写手机号会把人员和模板绑定死。使用 Phone 联系方式和 $sendtos 后，通知规则中选谁就 at 谁，后续调整人员不用改模板。
Q3：batchContactsAts 和 batchContactsJsonMarshal 分别解决什么问题？
A：前者生成 markdown 正文里的 @手机号 文本，后者生成钉钉请求体中 atMobiles 需要的 JSON 数组。钉钉 markdown at 人需要这两部分同时存在。
总结
夜莺钉钉 at 人的关键不是“把手机号塞进一个地方”，而是满足钉钉 markdown 消息的双重要求：正文里要有 @手机号，at.atMobiles 中也要有手机号数组。夜莺 v8.0.0-beta.8 以上版本已经内置模板函数，推荐通过 Phone 联系方式、$sendtos、batchContactsAts 和 batchContactsJsonMarshal 来完成这件事。
