本文将围绕钉钉机器人群聊消息的发送、查询已读状态与撤回操作进行详细讲解,帮助开发者快速掌握相关接口的调用方法与使用技巧。
创建机器人应用以及获取所需信息在上一篇文章已经详细说明:
钉钉企业内部机器人使用 Webhook 发送群聊消息的开发技巧-CSDN博客
一、功能概述
钉钉企业内部机器人不仅能够实现自动化消息推送,还支持对已发送消息的状态查询与撤回操作。具体功能包括:
- 发送群聊消息:通过API向指定群会话发送消息。
- 查询消息是否已读:获取机器人发送的消息在群内的阅读情况。
- 撤回已发送消息:静默撤回机器人发出的群聊消息。
这些功能特别适用于需要精确控制信息流的企业场景,如公告通知、数据提醒、任务调度等。
二、接入流程详解
步骤一:创建企业内部机器人
登录钉钉开发者后台,进入【应用开发】→【企业内部开发】页面,选择“机器人”类型创建一个新的应用。
步骤二:获取 AppKey 与 AppSecret
在机器人应用的【基础信息】页面中,可以查看并记录 AppKey
和 AppSecret
,这两个参数是后续获取访问令牌的关键凭证。
步骤三:申请接口权限
在【权限管理】页面中,勾选以下两个权限:
- 机器人
- 场景群
提交后无需等待审批,默认即开通权限。
步骤四:上线机器人应用
进入【版本管理与发布】页面,点击“上线”,将机器人状态变更为“已发布”,此时该机器人即可被正式调用。
步骤五:获取应用访问凭证 accessToken
调用所有服务端API前,需先通过 AppKey
和 AppSecret
获取 accessToken
。示例代码如下(Java):
public void getAccessToken() throws Exception {
Config config = new Config();
config.protocol = "https";
config.regionId = "central";
com.aliyun.dingtalkoauth2_1_0.Client client = new com.aliyun.dingtalkoauth2_1_0.Client(config);
GetAccessTokenRequest accessTokenRequest = new GetAccessTokenRequest()
.setAppKey("your_app_key")
.setAppSecret("your_app_secret");
GetAccessTokenResponse accessToken = client.getAccessToken(accessTokenRequest);
System.out.println(JSON.toJSONString(accessToken.getBody()));
}
步骤六:创建企业内部群
若没有可用群组,可通过调用创建群接口生成一个新群,并获取 openConversationId
,用于后续消息发送目标标识。
public void createGroup() throws ApiException {
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/chat/create");
OapiChatCreateRequest req = new OapiChatCreateRequest();
req.setName("测试群");
req.setOwner("user_id");
req.setUseridlist(Arrays.asList("user1", "user2"));
OapiChatCreateResponse rsp = client.execute(req, "access_token");
System.out.println(rsp.getBody());
}
步骤七:添加机器人至群聊
进入钉钉客户端,在对应群聊中添加之前创建的机器人,使其具备群内交互能力。
三、核心功能实现
功能一:发送群聊消息
调用 orgGroupSendWithOptions
接口,传入 openConversationId
、robotCode
、msgKey
和 msgParam
参数,发送消息并返回 processQueryKey
,用于后续查询或撤回操作。
OrgGroupSendRequest request = new OrgGroupSendRequest()
.setOpenConversationId("群ID")
.setRobotCode("机器人AppKey")
.setMsgKey("sampleText")
.setMsgParam("{\"content\":\"Hello World\"}");
功能二:查询消息已读状态
使用 orgGroupQueryWithOptions
接口,传入 processQueryKey
查询消息的阅读状态,适用于统计用户查看率或触发二次提醒逻辑。
OrgGroupQueryRequest request = new OrgGroupQueryRequest()
.setOpenConversationId("群ID")
.setRobotCode("机器人AppKey")
.setProcessQueryKey("消息唯一标识");
功能三:撤回已发送消息
通过 orgGroupRecallWithOptions
接口传入 processQueryKey
实现消息撤回,适用于误发、更新内容等场景。
OrgGroupRecallRequest request = new OrgGroupRecallRequest()
.setOpenConversationId("群ID")
.setRobotCode("机器人AppKey")
.setProcessQueryKeys(Arrays.asList("消息唯一标识"));
四、注意事项与最佳实践
- 权限校验:确保已正确申请“机器人”和“场景群”权限。
- 错误处理机制:在调用接口时应加入异常捕获逻辑,便于定位问题。
- 消息幂等性:建议为每条消息设置唯一标识,避免重复发送。
- token刷新机制:
accessToken
通常有有效期,建议定期刷新以保持连接有效性。 - 日志记录:记录每次发送、查询、撤回操作的日志,便于运维追踪。
五、总结
通过本文介绍的钉钉机器人消息交互机制,开发者可以构建出高度自动化和智能化的企业级应用。无论是日常运营通知、实时数据推送,还是用户行为分析,均可借助机器人完成高效沟通与反馈闭环。
未来随着钉钉生态的不断完善,企业内部协作将更加智能化、场景化。掌握这些接口的使用,将是每一位企业级应用开发者不可或缺的核心技能之一。
参考资料:
如需完整项目源码或接口调试工具,请关注本博客后续更新。