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