钉钉企业应用开发技巧:在单聊会话中实现互动卡片功能
随着企业数字化转型的加速,内部协作工具的智能化需求日益增长。钉钉作为国内领先的企业协同平台,提供了丰富的开放能力,支持开发者快速构建定制化应用。本文将详细介绍如何通过钉钉企业内部机器人,在单聊会话中实现互动卡片(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\"}";
}
六、结语
通过上述步骤,我们成功实现了钉钉企业内部机器人在单聊场景下发送互动卡片,并处理用户点击事件的能力。互动卡片不仅提升了交互效率,也为自动化审批、任务提醒等业务场景提供了强大的支持。
未来,开发者可以结合更多钉钉开放能力,如日程、审批流、考勤等,打造更智能的企业级应用。
参考资料:
- 钉钉开发者文档 - 互动卡片
- 钉钉IM API 文档