消息规范

本文面向外部业务项目负责人和开发人员。通知使用钉钉原生消息模板，不是 HTML/CSS 网页；卡片外框、宽度、颜色和按钮外观由钉钉客户端渲染。

通知中心固定展示项目来源和业务标题；业务项目决定正文排版、按钮文字及跳转目标。

1. 卡片类型和跳转

外部项目提交内容	通知中心使用的模板	收件人看到的效果
`actionUrl` 非空	`sampleActionCard`	原生 ActionCard，底部显示一个跳转按钮
`actionUrl` 未传或为空	`sampleMarkdown`	普通 Markdown 消息，没有底部按钮，外框和宽度可能与 ActionCard 不同

要实现“固定资产待审批”那种带按钮的卡片，提供 Markdown 正文和非空 actionUrl 即可；actionTitle 建议写明确动作，例如“立即审批”，未填写时默认“查看详情”。只填按钮文字但不填地址，不会生成按钮。

业务项目仍调用通知中心的 POST /v1/notifications，无需提交 msgKey、msgParam、singleTitle 或 singleURL，也无需直接调用钉钉 API。通知中心会把 actionTitle 映射为钉钉的 singleTitle，把实际发送的跳转地址映射为 singleURL。

按钮目标由业务项目的 actionUrl 决定。HTTP、HTTPS、内网 IP/域名和端口均可使用，无需为普通通知登记域名白名单；接收人的设备仍须能够访问该业务地址。只有启用钉钉 H5 免登且目标满足既有 HTTPS 登录规则时，通知中心才会包装到免登入口，最终仍回到指定业务页面。

2. 固定项目抬头

业务项目的 title 只填写业务主题，不要自行拼接项目名称。通知中心从当前鉴权项目的配置中取得名称，生成：

【项目名称】业务标题

发送给钉钉时，不只设置独立的 title 字段，还会在可见正文顶部加入 Markdown 标题，两种消息模板都如此：

### 【项目名称】业务标题

业务项目提交的 content

请勿在 content 中再重复同一条项目抬头或业务标题，以免出现双标题。除此之外，通知中心不添加固定时间、业务字段顺序或其它正文模板。

3. 完整 ActionCard 请求示例

以下为发送接口的 JSON 正文示例。花名、业务记录和地址均为示例值，接入时替换为本项目实际内容；接口鉴权与签名见接入指南。

{
  "idempotencyKey": "asset_disposal:53:海棠:v1",
  "recipientAlias": "海棠",
  "title": "资产报废待审批",
  "content": "**申请时间：** 2026年8月31日 15:58\n\n**资产：** 电脑桌（JS-CPU-0704）\n\n**申请人：** 示例员工\n\n**报废原因：** 资产损坏，申请报废。\n\n> 请核对资产及配件明细后处理。",
  "actionTitle": "立即审批",
  "actionUrl": "http://asset.example.com/workflows/disposals/53"
}

假设管理面板中的项目名称是“固定资产”，卡片正文为：

### 【固定资产】资产报废待审批

**申请时间：** 2026年8月31日 15:58

**资产：** 电脑桌（JS-CPU-0704）

**申请人：** 示例员工

**报废原因：** 资产损坏，申请报废。

> 请核对资产及配件明细后处理。

底部按钮显示“立即审批”，点击进入 http://asset.example.com/workflows/disposals/53。**字段名：** 表示加粗，空行用于分段，> 用于引用提示；这些只是可复用的示例排版，不要求所有业务项目都使用相同字段。

4. 字段与长度

字段	规则
`title`	必填，最长 100 字符；拼接项目名称后的最终标题最长 120 字符
`content`	必填，输入最长 4800 字符；纯文本或 Markdown 均可，显示在固定项目抬头之后
`actionTitle`	可选，最长 20 字符；有跳转地址但未填写时默认“查看详情”
`actionUrl`	可选；按业务项目提交值使用，不限制协议、公网/内网地址或项目域名白名单

当前发送实现会将“### + 最终标题 + 两个换行 + content”组成的钉钉 text 截取前 4800 字符。因此抬头也占显示额度，超长正文尾部可能被截断；业务详情宜放在跳转页面。业务项目仍对自己提交的原始 JSON 签名，无需预先插入抬头，保存的业务正文也不会因此改写。

5. 样式验收

确认钉钉聊天中的可见正文顶部有正确的 【项目名称】业务标题，不是只看消息摘要或接口返回值。
如需 ActionCard，使用非空 actionUrl 发送，确认正文格式、底部按钮和实际点击目标。
如果选择不提供跳转地址，应预期收到没有按钮的普通 Markdown 消息，而非相同外框的 ActionCard。
已发出的旧消息不会随代码、项目配置或测试页变化而自动更新。测试新的样式时创建一条新的测试事件并使用新幂等键；重试同一业务事件时仍复用原幂等键，不能借此绕过防重。

5.0 KiB Raw Permalink Blame History Unescape Escape