当前位置：首页 > news >正文

钉钉企业机器人开发技巧：实现单聊消息发送、状态查询与撤回

news 2025/7/8 8:54:45

在企业级应用开发中，钉钉作为国内领先的企业协作平台，提供了丰富的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();
}