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

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

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


一、概述

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

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

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

二、前置准备

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

  1. 企业认证:使用已认证的企业账号登录钉钉管理后台。
  2. 开发者权限:拥有“应用开发”相关权限,可访问钉钉开发者后台。
  3. 后端开发环境:具备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\"}";
}

六、结语

通过上述步骤,我们成功实现了钉钉企业内部机器人在单聊场景下发送互动卡片,并处理用户点击事件的能力。互动卡片不仅提升了交互效率,也为自动化审批、任务提醒等业务场景提供了强大的支持。

未来,开发者可以结合更多钉钉开放能力,如日程、审批流、考勤等,打造更智能的企业级应用。


参考资料:

  • 钉钉开发者文档 - 互动卡片
  • 钉钉IM API 文档
http://www.dtcms.com/a/270391.html

相关文章:

  • 学习日记-spring-day43-7.8
  • 基于物联网架构的温室环境温湿度传感器节点设计
  • 扣子Coze纯前端部署多Agents
  • WouoUI-Page移植
  • Java-Collections、Map
  • H3初识——入门介绍之常用中间件
  • 11款常用C++在线编译与运行平台推荐与对比
  • ffmpeg 中config 文件一些理解
  • Flutter基础(前端教程②-卡片列表)
  • study_WebView介绍
  • MYSQL进阶知识
  • 在keil中使用stlink下载程序报错Invalid ROM Table
  • Day07_C语言IO进程线程(重难点)
  • TensorFlow 和PyTorch的全方位对比和选择建议
  • Latex几种常用的花体
  • [2-02-02].第04节:环境搭建 - Linux搭建ES集群环境
  • [RPA] 影刀RPA基本知识
  • Kafka多组消费:同一Topic,不同Group ID
  • NV298NV312美光固态闪存NW639NW640
  • 基于mysqlfrm工具解析mysql数据结构文件frm表结构和数据库版本信息
  • 【Nginx】Nginx代理WebSocket
  • 扣子Coze远程连接数据库插件
  • C语言基础(1)
  • 【C++】AVL树底层思想 and 大厂面试
  • Python 的内置函数 slice
  • 为什么elementui的<el-table-column label=“名称“ prop=“name“ label不用写成:label
  • RS-232协议与RS485协议详解
  • [Backlog] 命令行界面CLI vs Web界面及服务端
  • 快手电商要投入多少钱?快手电商入驻条件和费用
  • 分布式无线工业数据采集终端应用场景简析