文本消息适合纯文字通知，Markdown 适合需要排版、链接或图片的场景，两者核心区别在于渲染引擎对格式的支持程度。
先说结论：文本消息渲染快且兼容性好，Markdown 消息视觉层级更丰富但需注意语法规范。
- 适合：简单通知用文本，公告报告用 Markdown。
- 重点看：Markdown 需要指定 title 和 text 字段，文本只需 content。
- 别忽略：两者都支持@功能，但 Markdown 图片链接需公网可访问。
快速处理思路
如果你正在调试机器人消息，可以直接参考以下 JSON 结构差异，确认 msgtype 字段及对应的内容容器。
文本消息 payload:
{
"msgtype": "text",
"text": {
"content": "月会通知"
},
"at": {
"isAtAll": true
}
}
Markdown 消息 payload:
{
"msgtype": "markdown",
"markdown": {
"title": "首屏会话透出的展示内容",
"text": "# 标题\n## 二级标题\n* 列表 1"
},
"at": {
"isAtAll": true
}
}为什么会这样
钉钉机器人网关接收到请求后，会根据 msgtype 字段选择不同的渲染引擎。文本类型被当作纯字符串处理，不做任何样式解析，因此展示效果统一且加载最快。Markdown 类型则会经过语法解析器，将#识别为标题、将![]识别为图片，从而在客户端呈现出富文本效果。
这种设计是为了平衡性能与表现力。简单告警不需要复杂样式，避免信息过载；而运营公告或技术报告需要重点突出，Markdown 提供了标准的格式化能力。公开资料中没有看到可靠的量化数据表明两者在送达速度上有显著差异，主要区别在于客户端渲染后的视觉呈现。
分步处理
1. 确定消息类型：根据内容复杂度选择。如果只有文字且无重点区分，选 text；如果有标题、列表或图片，选 markdown。
2. 构造请求体：文本消息将内容放在 text.content 中；Markdown 消息需同时填写 markdown.title 和 markdown.text。
3. 配置@提醒：两者均在根层级使用 at 对象。若@所有人，设置 isAtAll 为 true；若@指定人，填写 atUserIds 或 atMobiles。
4. 发送请求：通过 Webhook 地址 POST 请求，Content-Type 必须为 application/json。
怎么验证是否生效
1. 查看钉钉群聊：发送后直接在群内观察。文本消息无样式，Markdown 消息应显示加粗、标题或图片。
2. 检查首屏展示：Markdown 消息的 title 字段内容会显示在会话列表的预览中，文本消息则直接显示 content 前几个字。
3. 验证@效果：被@的成员会有特殊提醒标识，检查是否按预期触达。
常见坑
1. 图片链接失效：Markdown 中的图片 URL 必须是公网可访问地址，内网地址会导致客户端无法加载图片。
2. 语法错误导致渲染失败：如果 Markdown 语法不规范，部分客户端可能回退为纯文本显示，失去格式效果。
3. 手机电脑展示差异：有反馈指出 Markdown 消息在手机端和电脑端的排版细节可能存在细微差别，重要信息建议同时用文字强调。
4. 字符限制：文本消息内容建议控制在 500 字符以内，过长可能被截断或影响阅读体验。
参考来源
- 钉钉开放平台 - 消息类型与数据格式
- 钉钉开放平台 - 自定义机器人发送消息的消息类型
- 钉钉开放平台 - 在钉钉中，Webhook 方式支持哪些消息类型？
- 钉钉企业机器人发送 markdown 消息，手机电脑展示不同@钉钉客服