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

钉钉企业应用开发技巧：在单聊会话中实现互动卡片功能

news 2025/7/9 17:09:52

随着企业数字化转型的加速，内部协作工具的智能化需求日益增长。钉钉作为国内领先的企业协同平台，提供了丰富的开放能力，支持开发者快速构建定制化应用。本文将详细介绍如何通过钉钉企业内部机器人，在单聊会话中实现互动卡片（Interactive Card）消息的发送与响应，提升用户交互体验。

一、概述

互动卡片是一种增强型的消息格式，允许用户在聊天窗口中直接对卡片内容进行操作，如点击按钮、填写表单等，并将操作结果回传给服务端处理。这种交互方式不仅提升了用户体验，也简化了业务流程。

本教程重点介绍以下内容：

如何创建企业内部机器人；
如何配置消息接收地址与接口权限；
如何设计并发布互动卡片模板；
如何调用钉钉IM API实现卡片发送与更新；
如何处理卡片回调事件。

二、前置准备

在开始开发前，请确保已完成以下准备工作：

企业认证：使用已认证的企业账号登录钉钉管理后台。
开发者权限：拥有“应用开发”相关权限，可访问钉钉开发者后台。
后端开发环境：具备Java或其它语言开发能力，能部署HTTP服务用于接收回调请求。

三、接入流程详解

步骤一：创建企业内部机器人

登录钉钉开发者后台，进入【应用开发】→【企业内部开发】页面，选择【创建机器人】。填写基本信息并提交，系统将生成一个专属的机器人应用。

步骤二：获取 AppKey 和 AppSecret

在机器人【基础信息】页面中，记录下生成的 AppKey 和 AppSecret，这两个参数是后续调用API的身份凭证。

步骤三：设置消息接收地址

进入【开发管理】→【消息接收】，填写您的服务端接收地址（URL）。该地址将用于接收来自钉钉的事件通知，例如卡片按钮点击事件。

注意：需确保该URL对外网可达，并能正常接收POST请求。

步骤四：申请接口调用权限

在【接口调用权限】中，勾选【机器人】下的【企业内机器人发送消息】权限。此权限无需审批，默认开通。

步骤五：上线机器人

进入【版本管理与发布】页面，点击【上线】按钮，将机器人状态设置为“已发布”。只有上线后的机器人才能被实际使用。

提示：测试时建议创建真实的企业内部群进行调试，避免使用默认的测试群。

步骤六：创建互动卡片模板

登录钉钉管理后台，进入【应用管理】→【互动卡片】页面，选择【新建IM卡片】类型模板。根据业务需求编辑卡片内容，包括标题、字段、样式及按钮行为。

卡片按钮行为说明：

跳转交互：点击按钮后跳转至指定链接。
回传交互：点击按钮后向开发者服务器发送请求，适合执行审批、确认等操作。

完成编辑后，系统将生成唯一的 cardTemplateId，后续发送卡片时需要使用。

四、调用钉钉IM API实现卡片发送

4.1 初始化客户端

使用阿里云SDK初始化IM客户端：

public static com.aliyun.dingtalkim_1_0.Client createClient() throws Exception {Config config = new Config();config.protocol = "https";config.regionId = "central";return new com.aliyun.dingtalkim_1_0.Client(config);
}

4.2 发送互动卡片

调用 sendInteractiveCardWithOptions 接口发送卡片消息，核心参数如下：

cardTemplateId：卡片模板ID；
receiverUserIdList：接收者用户ID列表；
callbackRouteKey：注册回调地址时获取的路由键；
cardData：卡片数据，支持动态变量替换；
robotCode：即AppKey；
userIdType：用户ID类型（1表示加密ID）；

完整示例代码如下：

public void interactiveCardsSend() throws Exception {com.aliyun.dingtalkim_1_0.Client client = createClient();SendInteractiveCardHeaders headers = new SendInteractiveCardHeaders();headers.xAcsDingtalkAccessToken = "your-access-token";// 构建私有数据Map<String, String> privateParamMap = TeaConverter.buildMap(new TeaPair("key", "test"));PrivateDataValue privateDataValue = new PrivateDataValue().setCardParamMap(privateParamMap);// 构建卡片数据Map<String, String> cardParamMap = TeaConverter.buildMap(new TeaPair("title", "报销申请"),new TeaPair("type", "餐补费"),new TeaPair("amount", "1000元"),new TeaPair("reason", "北京出差"));SendInteractiveCardRequest.SendInteractiveCardRequestCardData cardData = new SendInteractiveCardRequest.SendInteractiveCardRequestCardData().setCardParamMap(cardParamMap);// 构造请求体SendInteractiveCardRequest request = new SendInteractiveCardRequest().setCardTemplateId("your-card-template-id").setReceiverUserIdList(Arrays.asList("user001")).setCallbackRouteKey("100").setCardData(cardData).setRobotCode("your-appkey").setPrivateData(Collections.singletonMap("user001", privateDataValue)).setUserIdType(1);try {SendInteractiveCardResponse response = client.sendInteractiveCardWithOptions(request, headers, new RuntimeOptions());System.out.println(JSON.toJSONString(response.getBody()));} catch (TeaException | Exception e) {e.printStackTrace();}
}

五、处理卡片回调事件

当用户点击卡片上的按钮时，钉钉会将事件数据以POST形式推送到您配置的回调地址。服务端需解析JSON数据并做出相应处理。

示例回调处理逻辑：

@RequestMapping(value = "/interactive-card-callback", method = RequestMethod.POST)
public String handleInteractiveCard(@RequestBody JSONObject json) {System.out.println("Received callback data: " + json.toJSONString());// 解析事件类型和参数String eventType = json.getString("eventType");JSONObject cardData = json.getJSONObject("cardData");if ("ACTION_CLICK".equals(eventType)) {String actionValue = cardData.getString("actionValue");String userId = json.getString("userId");// 根据actionValue执行业务逻辑if ("agree".equals(actionValue)) {System.out.println(userId + " 同意申请");} else if ("disagree".equals(actionValue)) {System.out.println(userId + " 拒绝申请");}}return "{\"result\": \"success\"}";
}