在企业级应用开发中，钉钉作为国内领先的企业协作平台，提供了丰富的API支持开发者构建定制化的工作流和自动化服务。其中，企业内部机器人是一个非常实用的功能模块，可以帮助企业快速实现通知推送、任务提醒等场景。
本文将详细介绍如何通过钉钉开放平台的机器人功能，实现以下三个核心能力：
- 发送单聊消息
- 查询单聊消息已读状态
- 撤回单聊消息
我们将从接入流程开始讲解，并结合Java代码示例演示关键接口的调用方式，帮助开发者快速上手。
一、预期效果概述
- 发送单聊消息：机器人可向指定用户发送单聊消息。
- 查询已读状态：虽然钉钉客户端不显示机器人消息的“已读”提示，但可通过API查询对方是否已查看消息。
- 消息撤回：机器人可以静默撤回已发送的消息（即消息直接消失）。
二、接入流程简介
步骤一：创建企业内部机器人应用
登录钉钉开发者后台 → 应用开发 → 企业内部开发 → 创建机器人应用。
步骤二：获取 AppKey 与 AppSecret
进入机器人应用的基础信息页面，记录下 AppKey 和 AppSecret，后续用于鉴权和获取访问令牌。
步骤三：添加接口调用权限
在权限管理中申请「企业内机器人发送消息」权限。该权限无需审批，默认自动开通。
步骤四：发布机器人应用
进入版本管理与发布页面，点击上线，使机器人处于“已发布”状态，方可对外提供服务。
步骤五：获取应用访问凭证 accessToken
使用 AppKey 和 AppSecret 调用钉钉 OAuth2 接口获取 accessToken，作为调用其他 API 的身份凭证。
示例代码：获取 accessToken
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("dingxxxxxx")
.setAppSecret("your_app_secret");
GetAccessTokenResponse response = client.getAccessToken(accessTokenRequest);
String accessToken = response.getBody().getAccessToken();
}
三、核心功能实现详解
功能一：发送单聊消息
调用 BatchSendOTO 接口发送单聊消息，并获取返回的 processQueryKey，用于后续查询或撤回操作。
Java 示例代码：
BatchSendOTOHeaders headers = new BatchSendOTOHeaders();
headers.xAcsDingtalkAccessToken = accessToken;
BatchSendOTORequest request = new BatchSendOTORequest()
.setRobotCode("dingxxxxxx") // 即 AppKey
.setUserIds(Arrays.asList("userId1")) // 用户ID列表
.setMsgKey("sampleMarkdown")
.setMsgParam("{\"text\": \"hello text\",\"title\": \"hello title\"}");
try {
BatchSendOTOResponse response = client.batchSendOTOWithOptions(request, headers, new RuntimeOptions());
System.out.println(JSONObject.toJSONString(response.getBody()));
} catch (TeaException | Exception e) {
e.printStackTrace();
}
注意：msgKey 是预定义的消息模板标识符，需提前在钉钉后台配置好对应格式。
功能二：查询消息是否已读
通过 BatchOTOQuery 接口，传入之前发送消息时获得的 processQueryKey，即可查询该消息是否已被目标用户阅读。
Java 示例代码：
BatchOTOQueryHeaders headers = new BatchOTOQueryHeaders();
headers.xAcsDingtalkAccessToken = accessToken;
BatchOTOQueryRequest request = new BatchOTOQueryRequest()
.setRobotCode("dingxxxxxx")
.setProcessQueryKey("your_process_query_key");
try {
BatchOTOQueryResponse response = client.batchOTOQueryWithOptions(request, headers, new RuntimeOptions());
System.out.println(JSONObject.toJSONString(response.getBody()));
} catch (TeaException | Exception e) {
e.printStackTrace();
}
响应结果中会包含每个用户的阅读状态，可用于判断消息是否被查看。
功能三：撤回单聊消息
调用 BatchRecallOTO 接口，传入一个或多个 processQueryKey，即可批量撤回消息。此操作为静默撤回，即消息不会在客户端显示撤回提示。
Java 示例代码：
BatchRecallOTOHeaders headers = new BatchRecallOTOHeaders();
headers.xAcsDingtalkAccessToken = accessToken;
BatchRecallOTORequest request = new BatchRecallOTORequest()
.setRobotCode("dingxxxxxx")
.setProcessQueryKeys(Arrays.asList("b5fe1xxx"));
try {
BatchRecallOTOResponse response = client.batchRecallOTOWithOptions(request, headers, new RuntimeOptions());
System.out.println(response.getBody());
} catch (TeaException | Exception e) {
e.printStackTrace();
}
四、注意事项
- 权限问题：确保已在钉钉后台正确配置并启用机器人发送消息权限。
- 用户ID问题：发送消息前应确保获取到目标用户的 userId，可通过通讯录接口获取。
- 消息类型限制：目前仅支持部分消息模板（如 Markdown、链接等），需提前配置 msgKey。
- 撤回时效性：消息撤回应在一定时间内完成，超时后无法撤回。
- 错误处理机制：建议在调用接口时加入重试机制与日志记录，提升系统健壮性。
五、结语
通过以上步骤与接口调用，我们可以在企业内部快速集成钉钉机器人，实现自动化消息推送、状态追踪与内容管理等功能。这不仅提升了企业内部沟通效率，也为构建智能化办公系统提供了有力支撑。
未来随着钉钉开放平台能力的不断拓展，相信企业机器人的应用场景将更加丰富，值得开发者持续关注与探索。
参考资料：