钉钉机器人如何获取用户userId并推送私聊消息

文章导读
在钉钉里做机器人开发,最容易混淆的就是机器人的形态。很多人拿着自定义群机器人的Webhook,想拿userId再发私聊,这条路径在权限上就走不通。所以要做的第一件事,不是写代码,而是确认你手上的机器人到底属于哪一种。
📋 目录
  1. A 先别急着改配置,确认机器人类型
  2. B 拿userId,推荐走免登授权
  3. C 会话内机器人,用回调事件识别发送者
  4. D 推私聊消息,走工作通知接口
  5. E 权限和边界:这些坑常在发版后冒出来
  6. F 改完怎么验证:先发最小化消息,再看错误码
A A

在钉钉里做机器人开发,最容易混淆的就是机器人的形态。很多人拿着自定义群机器人的Webhook,想拿userId再发私聊,这条路径在权限上就走不通。所以要做的第一件事,不是写代码,而是确认你手上的机器人到底属于哪一种。

先别急着改配置,确认机器人类型

在钉钉中,“机器人”一词可能指自定义群机器人和企业内部应用机器人两种形态。自定义群机器人只能通过Webhook发送群消息,无法获取用户的具体身份;而企业内部应用机器人则依托应用身份调用服务端API,能够获取用户的userId。因此,动手开发前务必先确认你拥有的机器人类型,这是判断后续技术方案能否成立的前提。只有企业自建应用或内部机器人,才具备获取用户身份并主动推送私聊消息的权限。可先查看应用后台的应用凭证和应用类型,若纯为群机器人,则无需继续设计用户ID获取环节。

确认方法很简单:登录开发者后台,找到你的应用。如果能看到AppKey、AppSecret、服务端API权限管理,说明是内部应用;如果只有一个Webhook地址和加签密钥,就是自定义群机器人。另外,还有一种情况是“企业内部应用”与“第三方应用”的区别,但企业内部应用通常都有完整的应用凭证。如果你只有机器人Webhook,那么后边的免登授权、工作通知推送,在设计阶段就可以先排除掉。

拿userId,推荐走免登授权

推荐的标准做法是通过钉钉的免登授权流程获取userId。前端页面在钉钉容器内获取免登授权码,将该code传给后端;后端使用应用的clientId和clientSecret,调用“获取用户token”或“获取用户信息”的开放接口,以code换取用户身份信息。需要特别注意的是,授权码通常是一次性的,且有效期很短,后端应及时消费。换接口返回的字段中会包含userId、姓名等,建议立即将userId与会话或登录态绑定,避免后续再次加载页面时重复请求授权。

这里要留意前后端的分工。前端只负责拿到临时授权码,不能接触clientSecret;后端收到code后,立即将其交换为token和用户信息,并和当前用户会话绑定。例如,后端可以维护一个session表,把userId写入会话;也可以直接下发一个自己签名的token,前端后续请求直接带这个token。这样即使用户重新打开页面,只要会话还有效,就不需要重新走钉钉授权。

交换token的请求通常是这样的(具体路径以开放平台当前接口为准):

钉钉机器人如何获取用户userId并推送私聊消息
POST /v1.0/oauth2/userAccessToken
Host: api.dingtalk.com
Content-Type: application/json

{
  "clientId": "你的AppKey",
  "clientSecret": "你的AppSecret",
  "code": "前端传入的authCode",
  "grantType": "authorization_code"
}

响应中会包含用户身份信息,你只需要提取userId。建议不要把整个响应直接转发给前端,而是只返回给前端一个自己业务侧的身份标识。

会话内机器人,用回调事件识别发送者

如果你的机器人已经安装在会话里,并且你只希望当用户主动发消息或@机器人时才知道是谁,可以不依赖免登,改用回调事件。钉钉会向你在后台配置的回调地址推送事件JSON,其中包含发送者标识。但是不同事件类型里,标识字段不一样,比如有的是senderUserId,有的是openId,而且事件内容本身可能是加密的。

处理回调的第一步是校验签名和解密,确认请求真的来自钉钉,然后再解析事件体。建议先不急着解析业务字段,直接把完整事件结构打印到日志里,对照事件类型确定发送者标识的准确路径。如果你订阅了多个事件,还要先判断eventType,再进入对应的解析分支,避免拿消息事件去套用户事件的结构。

如果你之前是通过免登已经拿到了userId,那么回调里的标识可以用来和已登录用户绑定。但要注意,回调中的openId可能不是userId,需要看事件字段的具体定义。

推私聊消息,走工作通知接口

拿到userId后,向用户推送消息通常使用“工作通知”类型。调用服务端消息发送接口,传入接收者的userId以及消息模板,可选择文本、markdown、卡片等形式。注意工作通知消息有发送频率限制,且用户主动取消订阅或停用后无法送达。建议先向企业内测试账号发送最小化文本消息,确认链路正常后再启正式模板。若企业启用了消息加密,发送前需按文档对消息内容做编码处理,否则接收端可能显示异常。

钉钉机器人如何获取用户userId并推送私聊消息

工作通知接口通常需要三个核心参数:应用凭证、接收者的userId、消息模板。有些接口还要求传agentId和msgtype。建议把发送动作封装成一个服务,统一管理模板和错误码。对于发送失败的情况,要区分是权限问题、参数问题还是用户不可达,不要把错误码一刀切。

权限和边界:这些坑常在发版后冒出来

整套流程能不能跑通,很大程度取决于应用权限。免登授权和工作通知分别需要“个人信息”或“通讯录”的相关权限,而且这些权限通常要管理员在开发者后台审批。如果接口返回“无权限”或“授权失败”,第一件事是去后台检查权限是否已开通,而不是反复改代码。另外,如果用户未激活钉钉、已离职或不是企业内部成员,免登和消息推送都可能失败。建议在获取userId前先调用通讯录接口确认用户在职状态,或者在失败日志中记录错误码,便于区分不可推状态与临时故障。

常见坑还有:把群机器人的webhook当作获取用户身份的入口,后面你会发现它根本没有用户接口;以及把userId和部门ID混用,发送工作通知只需要userId,但获取用户详情时可能要传根部门ID,两者不能互换。建议本地维护一张测试用户ID映射表,专门用来验证发送逻辑,同时仔细阅读每个接口的参数要求。

改完怎么验证:先发最小化消息,再看错误码

配置和代码都完成后,不要急着上模板消息,先做四个验证。第一,用测试账号走一遍免登授权,看后端日志里能否正确拿到userId。第二,用这个userId调用工作通知接口,发一条纯文本消息,确认他能收到。第三,在会话里私聊机器人或@机器人,查看回调日志,确认能解析出发送者标识,并且和免登拿到的userId能对应。第四,故意用一个离职账号或者错误userId试一次,看接口返回的错误码是否能被自己的日志体系捕获。

如果发送失败,优先看返回错误码中的提示信息。常见如权限不足、userId无效、消息频率超限。如果企业开了消息加密,还要确认发送前是否对内容做了正确编码。等最小链路验证通过后,再考虑markdown卡片、模板参数等增强功能。