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

钉钉企业内部机器人实现单聊会话互动开发指南

news 2025/7/8 17:34:35

本文将详细介绍如何基于钉钉平台创建企业内部机器人，并通过服务端API实现在单聊场景下的交互式对话，帮助开发者快速构建高效的机器人应用。

一、预期效果

本方案实现的功能包括：

用户与机器人进行一对一私聊；
机器人根据用户输入内容智能响应；
支持按钮点击跳转并触发下一轮对话；
实现多轮问答逻辑，如发票类型选择、发票内容说明、报销规则确认等；
可上线/下线控制机器人状态，便于测试和发布。

二、接入流程概述

创建机器人应用
获取AppKey与AppSecret
配置消息接收地址
申请接口调用权限
发布机器人版本
调用批量发送单聊消息接口
测试交互逻辑
下线机器人（可选）

三、详细开发步骤

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

登录钉钉开发者后台，进入【应用开发】→【企业内部开发】，创建一个新的“机器人”应用。填写基本信息后提交。

步骤二：获取 AppKey 和 AppSecret

进入机器人应用的【基础信息】页面，记录系统生成的 AppKey 和 AppSecret，这两个参数是后续调用接口的身份凭证，务必妥善保管。

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

在【开发管理】中，填写一个公网可访问的服务器地址作为消息接收 URL（Webhook），用于接收来自钉钉的消息推送。钉钉会以 POST 请求方式将用户消息推送到该地址。

注意：本地开发建议使用内网穿透工具（如 ngrok、frp）来临时暴露服务。

步骤四：添加接口调用权限

在【权限管理】→【接口调用权限】中，勾选“机器人”相关权限，特别是“企业内机器人发送消息”。该权限无需审批，系统默认开通。

步骤五：发布机器人

进入【版本管理与发布】页面，点击“上线”，将机器人状态更改为“已发布”。只有上线后的机器人，用户才能与其进行交互。

调试时请注意：测试群中的 @机器人无法获取 senderStaffId，建议使用真实企业内部群进行测试。

步骤六：实现单聊消息发送

钉钉提供了一个服务端 API —— 批量发送单聊消息接口（BatchSendOTO），可用于向指定用户发送个性化消息。

示例代码（Java Spring Boot）

以下是一个 Spring Boot 控制器示例，展示如何接收用户输入并返回对应的机器人响应：

@RequestMapping(value = "/robots", method = RequestMethod.POST)
public String helloRobots(@RequestBody(required = false) JSONObject json) throws Exception {System.out.println(JSON.toJSONString(json));String content = json.getJSONObject("text").getString("content");String userId = json.get("senderStaffId").toString();if (content.equals("发票")) {sendMessage1(userId);} else if (content.equals("发票要普票还是专票")) {sendMessage2(userId);} else if (content.equals("发票内容开什么")) {sendMessage3(userId);} else if (content.equals("差旅住宿普通发票可以报销吗")) {sendMessage4(userId);}return null;
}

消息模板定义

机器人支持多种消息格式，如 text、markdown、actionCard 等。例如，以下是一个带有三个选项按钮的 actionCard 消息：

{"title": "发票","text": "请问您是要咨询发票的什么内容呢","actionTitle1": "发票要普票还是专票","actionURL1": "dtmd://dingtalkclient/sendMessage?content=%E5%8F%91%E7%A5%A8%E8%A6%81%E6%99%AE%E7%A5%A8%E8%BF%98%E6%98%AF%E4%B8%93%E7%A5%A8","actionTitle2": "发票内容开什么","actionURL2": "dtmd://dingtalkclient/sendMessage?content=%E5%8F%91%E7%A5%A8%E5%86%85%E5%AE%B9%E5%BC%80%E4%BB%80%E4%B9%88","actionTitle3": "差旅住宿普通发票可以报销吗","actionURL3": "dtmd://dingtalkclient/sendMessage?content=%E5%B7%AE%E6%97%85%E4%BD%8F%E5%AE%BF%E6%99%AE%E9%80%9A%E5%8F%91%E7%A5%A8%E5%8F%AF%E4%BB%A5%E6%8A%A5%E9%94%80%E5%90%97"
}

其中，actionURL 中的内容必须进行 URL Encode，并且需与用户可能发送的问题完全一致，以便后端识别。