钉钉机器人如何实现消息已读回执功能

文章导读
在钉钉开放平台上,只有企业内部应用通过发送工作通知消息接口发出的消息才支持已读回执。普通的群机器人或者自定义机器人,因为属于会话消息,钉钉并不提供公开的已读回执查询能力。所以,如果你发现机器人发出去的消息无法获取已读状态,先确认是否使用了工作通知接口,并且应用是否具备发送工作通知的权限。实际开发中,这个权限需要应用管理员在开发者后台勾选并申请,审核通过后才能调用。
📋 目录
  1. 壹 先确认应用和消息通道
  2. 贰 发送成功后,taskId 是后续查询的唯一凭证
  3. 叁 已读回执有查询条件和时间窗口
  4. 肆 容易踩的坑:已读不等于看过,部门消息要按人匹配
  5. 伍 查询频率要照顾接口配额,别把回执查询做成实时系统
  6. 陆 上线前用一个测试账号验证状态变化
A A

先确认应用和消息通道

在钉钉开放平台上,只有企业内部应用通过发送工作通知消息接口发出的消息才支持已读回执。普通的群机器人或者自定义机器人,因为属于会话消息,钉钉并不提供公开的已读回执查询能力。所以,如果你发现机器人发出去的消息无法获取已读状态,先确认是否使用了工作通知接口,并且应用是否具备发送工作通知的权限。实际开发中,这个权限需要应用管理员在开发者后台勾选并申请,审核通过后才能调用。

这个判断是排错的第一步。群机器人的 webhook 地址通常在自定义任务里,发送后只有一个 messageId,没有 taskId,所以后续没有任何查询入口。工作通知消息却会走「应用管理 → 权限管理」里的发送工作通知接口,发送时要传 agent_id 和部门/用户列表。如果你正在对接一个第三方机器人,那大概率拿不到已读回执,因为第三方应用发工作通知需要企业授权,接口权限也不一样。

发送成功后,taskId 是后续查询的唯一凭证

已读回执功能依赖的两个核心接口是发送工作通知和查询已读状态。发送工作通知时,接口会返回一个taskId,这个taskId是后续查询的唯一凭证。查询时调用获取工作通知消息的已读回执接口,将taskId作为入参,返回结果中会列出每条消息的接收人以及对应的read字段,值为true表示已读,为false表示未读。注意,查询接口是异步性的,发送后立即查询可能返回未读,通常需要等待几秒到几分钟才准确,具体延迟取决于钉钉服务器的处理状况。

所以代码里不要只打印 taskId,要把它存下来。建议至少留一张表,字段可以这样定义:

task_id        TEXT PRIMARY KEY,
send_time      DATETIME,
agent_id       TEXT,
receiver_list  TEXT,
read_status    TEXT,
last_query_at  DATETIME

后续定时任务按 send_time 排序,把未查询的 task_id 分批取出来调用查询接口。如果进程重启,表里的数据仍然在,不会因为内存丢失而断掉。

钉钉机器人如何实现消息已读回执功能

已读回执有查询条件和时间窗口

对已读回执的查询需要满足两个条件:一是消息必须已经发送成功,即发送接口返回的errcode为0,并且拿到了taskId;二是消息在钉钉服务器上的保留时间不超过24小时。超过24小时的历史消息会无法查到回执,此时接口会返回消息不存在或已过期的错误。因此,如果你要做已读率统计,建议在消息发送后15分钟到24小时之间完成查询,既避开延迟高峰又不会丢失数据。

这里要强调“发送成功”只是发送接口返回成功,不代表每个接收人侧已经展示。实际观察中,消息进入工作通知栏还有个分发过程,所以建议把查询做成多轮:发送后 10 秒查一次、1 分钟查一次、10 分钟查一次,后面把 read=true 的数量稳定下来就算最终回执。不要只查一次,也不要每几秒就轮询一次,因为查询接口本身也有延迟。

容易踩的坑:已读不等于看过,部门消息要按人匹配

开发中一个常见的坑是把已读回执等同于用户已阅读内容。实际上,钉钉的已读回执只表示客户端已经收到并展示过该消息,不区分用户是否真正打开查看过,也不记录具体阅读时长。另一个坑是,当消息发送给一个部门时,查询接口返回的是部门内所有成员的状态,但如果你需要单独判断某个人,必须通过接口先拉取部门用户列表,再结合返回的userid逐个匹配,否则无法精确统计到个人是否已读。

这个“展示过”的含义可以用在工作通知场景里:只要消息进入了工作通知栏,客户端一般会主动拉取并标记为已读,所以它可以作为消息触达的参考,但不能当作“用户仔细阅读了内容”的依据。如果你需要知道用户是否点开了链接,那需要自己在前端埋点,并通过 userId 关联回这张任务表。

钉钉机器人如何实现消息已读回执功能

查询频率要照顾接口配额,别把回执查询做成实时系统

已读回执接口有调用频率限制,具体配额与应用类型和等级有关,不要在大规模发送时同时并发查询所有消息,以免触发限流。而且在钉钉的开放接口中,已读回执仅支持逐条消息查询,不支持批量获取。因此,对于高频场景,建议将返回的taskId持久化,通过定时任务分批次错峰查询,并在遭遇限流错误码时做退避重试。这样做可以降低接口压力,也避免因瞬时并发导致查询失败影响数据完整性。

退避重试可以写得很简单,遇到限流错误码就 sleep 一段时间再试,例如第一次等 2 秒,第二次等 4 秒,最多重试几次。查询完成后把 read_count 写回本地,不依赖每次现查。

上线前用一个测试账号验证状态变化

实现已读回执后,可以通过对比发送总数和已读总数来验证功能是否正常。发送工作通知接口返回的taskId,配合收件人列表,可以统计出本次消息的接收人数。查询已读回执时,计算返回结果中read字段为true的数量,两者相减即为未读人数。在测试阶段,建议先用一个测试账号给自己发送消息,然后分别在发送后10秒、1分钟、10分钟触发查询,观察read字段的变化,确认状态由false转为true后,再部署到生产环境。

这里建议在测试环境里把“发送总数”和“已读总数”两个数打在同一行日志里,每次查询都输出。如果发送总数一直对不上,先检查收件人列表是否包含了非企业成员;如果已读总数卡在一个值不变,可能是部门消息里有用户不活跃或离职,需要按用户维度去核对。这样上线后遇到问题,至少能通过日志定位是发送侧还是查询侧。