钉钉机器人 SDK 不同版本之间消息体结构有哪些变化

钉钉机器人消息体结构的变化主要取决于接入方式（Webhook vs 服务端 API）以及 SDK 版本（2.x vs 3.0+）。新项目建议直接接入新版 API 并使用 SDK 3.0 以上版本，旧版 SDK 与新版底层架构不兼容，需调整代码逻辑。

核心结论：SDK 3.0 为重大版本升级，底层架构变动导致与旧版不互通；Webhook 与 API 的消息体结构存在本质差异。

版本选择：新应用优先使用 SDK 3.0+ 接入新版服务端 API；旧应用若需新能力需迁移。
结构差异：Webhook 仅需 JSON 体；API 方式需配合 access_token 或签名，且参数结构不同。
验证关键：必须同时检查 HTTP 状态码（200）与响应体 errcode（0）。

消息体结构对比

不同接入方式的消息体 JSON 结构存在明显差异，以下是常见文本消息的结构对照：

1. Webhook 方式（自定义机器人）

无需 SDK，直接 HTTP POST，Content-Type 必须为 application/json。

{
    "msgtype": "text",
    "text": {
        "content": "我是文本消息"
    },
    "at": {
        "atMobiles": ["150XXXXXXXX"],
        "isAtAll": false
    }
}

2. 服务端 API 方式（内部应用）

通过 SDK 或 API 接口发送，旧版接口与新版的参数封装有所不同。

旧版 API (oapi/robot/send):

{
    "msgtype": "text",
    "text": {
        "content": "我是文本消息"
    },
    "at": {
        "atMobiles": ["150XXXXXXXX"]
    }
}

新版 API (SDK 3.0+):

SDK 3.0 通常封装了请求模型，底层仍兼容上述结构，但初始化与认证方式变更。部分新接口采用 msgKey 模式：

{
    "msgKey": "sampleText",
    "msgParam": "{\"content\":\"我是文本消息\"}",
    "receiverId": "chatId"
}

SDK 3.0 代码迁移示例

SDK 3.0 采用了新的配置初始化方式，旧版 Client 初始化方法不再适用。

Java 示例

// 旧版初始化 (已不推荐)
DingTalkClient client = new DefaultDingTalkClient("URL");
OapiRobotSendRequest request = new OapiRobotSendRequest();

// 新版 SDK 3.0 初始化
Config config = new Config();
config.protocol = "https";
config.regionId = "central";
config.accessKeyId = "yourAccessKeyId";
config.accessKeySecret = "yourAccessKeySecret";
config.endpoint = "api.dingtalk.com";
Client client = new Client(config);

// 发送消息
SendRobotMessageRequest request = new SendRobotMessageRequest();
request.setAgentId("agentId");
request.setUserIdList("userId");
request.setMsgKey("sampleText");
request.setMsgParam("{\"content\":\"测试\"}");
SendRobotMessageResponse response = client.sendRobotMessage(request);

验证与排查步骤

发送消息后，需按照以下顺序验证是否成功，避免误判：

检查 HTTP 状态码：确认响应状态码为 200。若为 4xx 或 5xx，说明请求未到达业务逻辑层。
检查业务错误码：解析响应体 JSON，确认 errcode 字段为 0。
检查错误信息：若 errcode 不为 0，查看 errmsg 定位具体原因。

注意：不要仅根据 errmsg 判断成功与否，必须检查 errcode 是否为 0。某些情况下 HTTP 200 但业务失败。

常见错误与解决方案

40035 错误：通常意味着 Content-Type 头未设置为 application/json，或 JSON 主体格式不规范。检查是否有多余空格或转义错误。
SDK 版本冲突：SDK 3.0 与旧版 SDK 依赖包不能共存，混用会导致类找不到或方法失效。迁移时需清理旧依赖。
消息类型不支持：Webhook 方式不支持图片、语音、文件等类型，若需发送此类消息需改用服务端 API 方式。
签名失效：API 方式需计算签名，确保时间戳在有效期内，且加签密钥正确。

参考文档

钉钉开放平台 - 服务端 API 文档
钉钉开放平台 - 服务端 SDK 下载与指引
阿里云帮助文档 - SDK 版本演进说明
钉钉开放平台 - 机器人消息发送类型详解