钉钉旧版机器人与新版群机器人接口有什么区别对比

钉钉机器人主要分为旧版自定义机器人（Webhook）和新版企业内部应用机器人（Open API 2.0）。如果只是需要在群里推送简单通知，旧版自定义机器人足够；如果需要单聊交互、获取用户信息或复杂业务集成，必须使用新版企业内部应用机器人。

核心结论：两者定位不同，自定义机器人轻量但功能受限，企业内部机器人权限高但开发成本高。

选型建议：简单群消息推送用自定义机器人；复杂业务交互、单聊消息用企业内部机器人。
关键差异：自定义机器人不支持单聊会话；企业内部机器人需配置应用可见范围。
接口规范：新应用建议接入 Open API 2.0 版服务端 API，旧版 API 不再开放新能力。

核心接口差异对比

旧版自定义机器人基于 Webhook 机制，无需鉴权流程但功能单一；新版企业内部机器人属于钉钉开放平台应用体系，需获取 access_token，支持更多交互能力。

对比项	旧版自定义机器人 (Webhook)	新版企业内部机器人 (Open API 2.0)
接入方式	Webhook 地址直接推送	创建企业内部应用，调用 Open API
鉴权机制	access_token 包含在 Webhook 链接中	需通过 appKey/appSecret 获取 access_token
消息类型	支持 text、markdown、链接等基础类型	支持互动卡片、模板卡片等高级类型
会话场景	仅支持群聊，不支持单聊	支持群聊、单聊、工作通知
用户信息	无法获取用户敏感信息	可获取用户 UserID、手机号（需权限）
文档参考	钉钉开放平台 - 自定义机器人	钉钉开放平台 - 企业内部应用

实操代码示例

1. 旧版自定义机器人 (Webhook)

适用于无需鉴权的简单群通知。注意 Webhook 地址泄露会导致安全风险，建议开启自定义关键词或 IP 白名单。

curl 'https://oapi.dingtalk.com/robot/send?access_token=YOUR_WEBHOOK_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "msgtype": "text",
  "text": {
    "content": "测试消息：服务器报警" 
  },
  "at": {
    "isAtAll": true
  }
}'

2. 新版企业内部机器人 (Open API 2.0)

适用于需要身份识别或复杂交互的场景。需先通过 https://api.dingtalk.com/v1.0/oauth2/accessToken 获取 access_token。

# 1. 获取 access_token
curl -X POST 'https://api.dingtalk.com/v1.0/oauth2/accessToken' \
-H 'Content-Type: application/json' \
-d '{
  "appKey": "YOUR_APP_KEY",
  "appSecret": "YOUR_APP_SECRET"
}'

# 2. 发送消息 (示例：发送工作通知)
curl -X POST 'https://api.dingtalk.com/v1.0/robot/oms/messages/sendByOpenId' \
-H 'Content-Type: application/json' \
-H 'x-acs-dingtalk-access-token: YOUR_ACCESS_TOKEN' \
-d '{
  "agentId": "YOUR_AGENT_ID",
  "userIdOpenIds": ["USER_OPEN_ID"],
  "msgKey": "sampleText",
  "msgParam": "{\"content\":\"测试消息：新版 API 推送\"}"
}'

配置与迁移注意事项

可见范围配置：企业内部机器人需与应用可见范围保持一致。钉钉开放平台曾调整策略，存量机器人需迁移至企业内部应用中，可见范围从“全员可见”变为“与应用可见范围一致”。
卡片数据填写：若使用新版接口（创建卡片、投放卡片等），依照 API 卡片数据说明填写。若使用旧版接口创建、更新卡片时，content 字段仅支持 String 类型，复杂结构需使用 sys_full_json_obj 字段传递 JSONObject。
API 版本选择：新应用建议接入 2.0 版服务端 API（RESTful 风格），文档地址可参考钉钉开放平台文档中心。已有应用若继续使用旧版 API，注意旧版接口不再开放新能力。

验证与常见错误排查

部署后建议通过以下步骤验证接口连通性及权限配置。

发送测试消息：通过 Webhook 或 API 发送一条文本消息到目标群或单聊，确认接收正常。
检查权限：尝试调用用户信息接口，确认是否能获取到预期数据（自定义机器人无法获取）。
查看日志：在开放平台查看应用调用日志，确认 API 请求状态码为成功。

常见错误码及解决方案：

invalid webhook：Webhook 地址错误或已失效，请重新创建机器人获取新地址。
isv permission denied：企业内部机器人权限不足，检查开放平台应用权限配置及可见范围。
unsupported msg type：消息类型不支持，自定义机器人不支持单聊会话，强行调用会失败。
param required：参数缺失，旧版接口非 String 参数需构建 JSONObject 并通过 sys_full_json_obj 字段传递。