Skip to main content

​
钉钉机器人对接指南

​
概述

本模块实现了钉钉机器人的 HTTP 回调模式对接。钉钉机器人收到用户消息后，会将消息 POST 到配置的回调地址，我们处理消息后直接在响应中返回回复内容。

​
架构设计

用户发送消息 → 钉钉服务器 → 回调我们的接口 → 调用AI服务 → 直接返回响应 → 用户收到回复

​
核心组件

  • DingTalkRobotEndpoint - 处理钉钉回调的 REST 接口
  • RobotChatService - 统一的机器人聊天服务
  • DingTalkChannelConfig - 渠道配置（appKey, appSecret）

​
回调地址格式

POST /robot/dingtalk/callback/{apiKey}

​
消息处理流程

​
1. 接收消息

钉钉发送的消息请求格式： 
{
  "msgId": "xxx",
  "msgtype": "text",
  "text": {
    "content": "用户消息内容"
  },
  "senderStaffId": "xxx",
  "senderNick": "用户昵称",
  "senderCorpId": "企业ID",
  "conversationId": "会话ID",
  "conversationType": "1",
  "chatbotUserId": "机器人ID",
  "atUsers": [
    {
      "dingtalkId": "xxx",
      "staffId": "xxx"
    }
  ],
  "isAdmin": false,
  "sessionWebhook": "https://oapi.dingtalk.com/robot/sendBySession?session=xxx",
  "sessionWebhookExpiredTime": 1234567890,
  "createAt": 1234567890
}

​
2. 返回回复

直接在 HTTP 响应中返回钉钉消息格式： 
{
  "msgtype": "text",
  "text": {
    "content": "AI回复内容"
  }
}

​
与其他平台的差异

特性钉钉机器人飞书机器人企业微信机器人
请求格式明文 JSON明文/加密 JSON加密 JSON
响应方式直接返回需主动调API发送直接返回加密消息
SDK 依赖无需SDK需要SDK需要SDK
加密配置无可选必须
会话Webhook提供（可选用）无无

​
配置说明

在 LangChat 管理后台创建 API 密钥时，选择”钉钉”渠道，配置以下信息：
配置项必填说明获取位置
appKey是应用AppKey钉钉开放平台 → 应用详情 → 凭证与基础信息
appSecret是应用AppSecret钉钉开放平台 → 应用详情 → 凭证与基础信息

​
钉钉后台配置

​
步骤一：创建应用

  1. 登录 钉钉开放平台
  2. 创建企业内部应用
  3. 获取 AppKey 和 AppSecret

​
步骤二：添加机器人能力

  1. 进入应用详情 → 添加应用能力
  2. 选择「机器人」能力
  3. 配置机器人名称和头像

​
步骤三：配置消息接收

  1. 进入「机器人」配置页面
  2. 消息接收模式选择：HTTP模式
  3. 消息接收地址填写：https://你的域名/robot/dingtalk/callback/{apiKey}
  4. 点击保存

​
步骤四：发布应用

  1. 创建应用版本
  2. 申请上线
  3. 管理员审批通过后生效

​
会话类型

钉钉机器人支持两种会话类型：
conversationType说明特点
1单聊用户与机器人私聊
2群聊群内 @机器人 触发

​
主动发送消息（可选）

钉钉在回调请求中提供了 sessionWebhook 字段，可用于主动向用户发送消息： 
// sessionWebhook 有效期内可多次调用
String webhook = message.getSessionWebhook();
// POST 请求到 webhook 地址，消息格式同响应格式
注意：sessionWebhook 有过期时间（sessionWebhookExpiredTime），过期后无法使用。

​
注意事项

​
响应时间

钉钉对回调响应没有严格的 3 秒超时限制（不同于飞书），但建议：
  • 控制 AI 处理时间，避免用户等待过长
  • 复杂任务可先返回”正在处理”，再通过 sessionWebhook 发送结果

​
消息去重

钉钉可能会重复推送同一条消息（网络问题），建议：
  • 根据 msgId 进行去重
  • 避免重复处理和回复

​
@机器人

在群聊场景中：
  • 用户需要 @机器人 才能触发消息
  • atUsers 字段包含被 @的用户列表
  • text.content 中会包含 @机器人 的文本（需要清理）

​
域名配置

LangChat 前端 .env 文件中的 VITE_API_URL 配置会影响显示的回调地址：
  • 本地开发时显示 http://127.0.0.1:8100
  • 生产环境应配置为真实的公网域名

​
支持的消息类型

当前支持的消息类型：
  • text - 文本消息
后续可扩展：
  • image - 图片消息
  • file - 文件消息
  • audio - 语音消息
  • markdown - Markdown消息
  • actionCard - 卡片消息

​
错误处理

错误场景返回内容
API Key 无效配置错误：无效的API Key
渠道类型不匹配配置错误：渠道类型不匹配
渠道配置无效配置错误：渠道配置无效
消息内容为空消息内容为空
处理异常处理失败，请稍后重试

​
相关文档