先说明一下处理范围。这里说的是钉钉自定义机器人,也就是通过 Webhook 地址推送消息的那一种。如果你用的是企业内部应用机器人,接口和权限模型会不一样,Markdown 支持情况也要单独确认。排障时,先不要急着改代码,把消息类型、请求体字段和客户端版本这些因素分开看,通常更容易定位。
想把 Markdown 内容发给钉钉机器人,可以按以下方式构造发送内容:向机器人 Webhook 地址发起 POST 请求,请求体为 JSON 格式,其中 msgtype 固定为 markdown,然后提供 title 参数作为消息标题(会显示在消息顶部),text 参数写入 Markdown 内容。例如 text 中可以写「### 标题\n 这是 **加粗** 文字」这样的内容。注意 text 中的换行符需要用 \n 表示,不能直接回车,否则 JSON 解析可能出错。发送成功后返回结果中 errcode 为 0,表示投递成功。
先看 msgtype,别让 Markdown 被当成纯文本
很多人把 Markdown 写进 text 字段,却发现客户端老老实实显示成一堆井号和星号。这不是语法写错,而是消息类型没对上。从服务端角度看,消息是否渲染是由 msgtype 决定的,不是由文本内容自己决定的。因此,普通文本类型哪怕传入完整的 Markdown 片段,也只会被当作纯文本透传。
钉钉自定义机器人是否支持 Markdown,关键在于发送消息时设置的消息类型是否为 markdown。若使用普通文本类型,即使 text 字段中写了 Markdown 语法,服务端也会按纯文本处理,不会渲染成格式。只有将 msgtype 明确设置为 markdown,并同时提供 title 和 text 字段,钉钉客户端才会对 text 内容进行 Markdown 渲染。因此,判断一个机器人是否支持 Markdown,不能只看文档描述,要实际发送一条带标题和加粗文本的消息,观察是否出现格式效果。
如果你是接到同事反馈后才来复查,先别改业务代码,直接抓一条最近发送的消息体,看 msgtype 是不是小写 markdown。大小写错误也会导致回退到文本模式。这类问题通常几分钟就能定位,改完重发一条带标题的测试消息就能看到差异。
构造 Markdown 消息体,并确认返回码
想把 Markdown 内容发给钉钉机器人,可以按以下方式构造发送内容:向机器人 Webhook 地址发起 POST 请求,请求体为 JSON 格式,其中 msgtype 固定为 markdown,然后提供 title 参数作为消息标题(会显示在消息顶部),text 参数写入 Markdown 内容。例如 text 中可以写「### 标题 这是 **加粗** 文字」这样的内容。注意 text 中的换行符需要用 表示,不能直接回车,否则 JSON 解析可能出错。发送成功后返回结果中 errcode 为 0,表示投递成功。
落到实际请求里,完整结构大概是这样:
POST https://oapi.dingtalk.com/robot/send?access_token=<你机器人的access_token>
Content-Type: application/json
{
"msgtype": "markdown",
"markdown": {
"title": "测试消息",
"text": "### 巡检结果\n服务运行正常,请忽略此条。"
}
}这里把 title 和 text 放在 markdown 字段内,是钉钉服务端常见的封装方式。如果你用的是现成 SDK,直接看它的请求体再对照调整。返回结果里 errcode 为 0,说明请求到达钉钉并且参数解析通过,但渲染是否成功仍要以客户端显示为准。
表格和代码块的渲染不稳定
钉钉机器人支持的 Markdown 是子集,不是完整规范。标题、加粗、斜体、链接、无序列表这类基础语法通常可用,但表格和代码块的兼容性不稳定,具体行为跟客户端版本还有关系。如果发现表格显示成普通文字,优先改成列表或直接贴截图,不必再试更多分隔符写法。图片语法虽然可用,图片地址必须是公网可访问,内部地址通常拿不到图。
发送失败时按这几个信号排查
如果你发送了一条 Markdown 消息但没有看到预期格式,可以按下面几步排查:第一,检查请求体中的 msgtype 是否为 markdown,以及大小写是否正确;第二,检查 text 字段中的内容是否被正确的转义,比如双引号、斜杠是否被 JSON 解析器改变;第三,用钉钉提供的「发送消息失败」返回码,可以通过接口响应中的 errmsg 字段判断问题,比如消息为空、非法参数等;第四,在钉钉客户端中刷新会话,看看是否有缓存导致未更新。如果以上都正常,建议换一种简单的 Markdown 语法(如 **加粗**)再测试,以排除单个语法兼容问题。
这里特别提一下客户端缓存。移动端和桌面端的渲染策略不完全一致,同一份内容在两个端显示可能有差异。建议发送者和接收者分别在手机端和电脑端各看一次,否则容易把客户端差异误判成接口问题。
文本长度、限流和后端兜底
超长内容和短时间高频请求是两个常见边界。钉钉对单条消息长度有限制,内容太长会被截断,所以建议把正式发送内容控制在几千字符内。对同一个 Webhook 的调用频率也有限制,短时间集中发送会触发限流,消息可能被延迟或丢弃。如果后续有批量推送场景,建议在后端加发送队列,记录每次请求的返回码,并针对限流做退避重试。另外,不要在文本里嵌套 HTML 标签,钉钉不渲染 HTML,只会原样显示标签文本。
如果你在接入过程中发现同一种语法在某个版本客户端上正常、在另一个版本上不渲染,通常不是你的代码问题,而是客户端实现差异。把这类兼容性结论记到自己的排障文档里,后续再遇到可以直接跳过。