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

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


一、概述

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

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

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

二、前置准备

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

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

三、接入流程详解

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

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

步骤二:获取 AppKey 和 AppSecret

在机器人【基础信息】页面中,记录下生成的 AppKeyAppSecret,这两个参数是后续调用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\"}";
}

六、结语

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

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


参考资料:

相关推荐
灋✘逞_兇6 分钟前
Node.Js是什么?
服务器·javascript·node.js
kfepiza29 分钟前
Linux的`if test`和`if [ ]中括号`的取反语法比较 笔记250709
linux·服务器·笔记·bash
vvw&2 小时前
Linux 中的 .bashrc 是什么?配置详解
linux·运维·服务器·chrome·后端·ubuntu·centos
Clownseven4 小时前
SFTP服务器搭建实战:腾讯云 Linux 上的快速安全文件传输方案
linux·服务器·腾讯云
脑袋大大的5 小时前
钉钉企业应用开发技巧:查询表单实例数据新版SDK指南
java·钉钉·企业应用开发
科智咨询7 小时前
双轮驱动:政策激励与外部制约下的国产服务器市场演进
运维·服务器·gpu算力
行而不知7 小时前
家庭网络中的服务器怎么对外提供服务?
运维·服务器·内网穿透·ddns
X_taiyang187 小时前
超越公有云:在裸金属服务器上构建低成本、高性能的静态资源服务
服务器·minio
weixin_456732597 小时前
Live555-RTSP服务器
运维·服务器