Skip to main content

​
飞书机器人对接指南

​
概述

本模块实现了飞书机器人的 HTTP 回调模式对接。飞书机器人收到用户消息后，会将消息 POST 到配置的回调地址，我们处理消息后通过飞书 API 主动发送回复。

​
架构设计

用户发送消息 → 飞书服务器 → 回调我们的接口 → 调用AI服务 → 飞书API发送回复 → 用户收到回复

​
核心组件

  • FeishuRobotEndpoint - 处理飞书回调的 REST 接口
  • RobotChatService - 统一的机器人聊天服务
  • FeishuChannelConfig - 渠道配置（appId, appSecret, encryptKey）
  • com.lark.oapi.Client - 飞书官方 SDK 客户端（用于发送消息）

​
回调地址格式

POST /robot/feishu/callback/{apiKey}

​
消息处理流程

​
1. URL 验证

飞书在配置回调地址时会发送验证请求： 
{
  "challenge": "ajls384kdjx98XX",
  "token": "xxx",
  "type": "url_verification"
}
响应格式： 
{
  "challenge": "ajls384kdjx98XX"
}

​
2. 接收消息事件

飞书发送的消息事件格式（v2.0）： 
{
  "header": {
    "event_id": "xxx",
    "event_type": "im.message.receive_v1",
    "create_time": "1234567890",
    "token": "xxx",
    "app_id": "cli_xxx",
    "tenant_key": "xxx"
  },
  "event": {
    "sender": {
      "sender_id": {
        "open_id": "ou_xxx",
        "user_id": "xxx"
      },
      "sender_type": "user"
    },
    "message": {
      "message_id": "om_xxx",
      "chat_id": "oc_xxx",
      "chat_type": "p2p",
      "message_type": "text",
      "content": "{\"text\":\"用户消息\"}"
    }
  }
}

​
3. 发送回复

通过飞书 SDK 调用消息发送 API： 
client.im().message().create(
    CreateMessageReq.newBuilder()
        .receiveIdType(CreateMessageReceiveIdTypeEnum.CHAT_ID)
        .createMessageReqBody(CreateMessageReqBody.newBuilder()
            .receiveId(chatId)
            .msgType("text")
            .content("{\"text\":\"AI回复内容\"}")
            .build())
        .build()
);

​
与其他平台的差异

特性飞书机器人钉钉机器人企业微信机器人
请求格式明文/加密 JSON明文 JSON加密 JSON
响应方式需主动调API发送直接返回直接返回加密消息
SDK 兼容性需手动处理（javax/jakarta）无需SDK需要SDK
加密配置可选无必须

​
配置说明

在 LangChat 管理后台创建 API 密钥时，选择”飞书”渠道，配置以下信息：
配置项必填说明获取位置
appId是应用AppId飞书开放平台 → 应用详情 → 凭证与基础信息
appSecret是应用AppSecret飞书开放平台 → 应用详情 → 凭证与基础信息
encryptKey否加密密钥飞书开放平台 → 事件订阅 → 加密策略

​
飞书后台配置

​
步骤一：创建应用

  1. 登录 飞书开放平台
  2. 创建企业自建应用
  3. 获取 App ID 和 App Secret

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

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

​
步骤三：配置事件订阅

  1. 进入「事件订阅」配置
  2. 请求地址填写：https://你的域名/robot/feishu/callback/{apiKey}
  3. 点击验证（确保服务已部署）
  4. 添加事件：接收消息 im.message.receive_v1

​
步骤四：配置权限

在「权限管理」中开通以下权限：
  • im:message - 获取与发送单聊、群组消息
  • im:message:send_as_bot - 以应用的身份发消息

​
步骤五：发布应用

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

​
加密配置（可选）

如果在飞书后台配置了 Encrypt Key：
  1. 飞书会将所有回调内容加密后发送
  2. 请求体格式变为：{"encrypt": "加密内容"}
  3. 需要在 LangChat 渠道配置中填写相同的 encryptKey
  4. 系统会自动解密消息内容
解密算法：AES-256-CBC，密钥为 encryptKey 的 SHA256 哈希值。

​
注意事项

​
3秒超时限制

飞书要求在 3 秒内响应回调请求，否则会触发重试。因此：
  • 接口立即返回 {"code":0,"msg":"ok"}
  • AI 处理和消息发送在异步线程中执行

​
SDK 兼容性说明

飞书官方的 oapi-sdk-servlet-ext 使用 javax.servlet 包，与 Spring Boot 3 的 jakarta.servlet 不兼容。因此本模块：
  • 仅使用 oapi-sdk 核心包
  • 手动处理请求解析和消息解密
  • 使用 SDK 的 Client 发送消息

​
消息去重

飞书可能会重复推送同一条消息（网络问题或超时重试），建议：
  • 根据 message_id 进行去重
  • 避免重复处理和回复

​
支持的消息类型

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

​
相关文档