Skip to main content

​
飞书接入

PAI 支持通过飞书开放平台的事件订阅机制接入，适用于企业内部部署场景。当前支持单聊（P2P）模式。

​
创建飞书应用

1

创建应用

登录 飞书开放平台，进入开发者后台，创建一个企业自建应用
2

获取凭证

在「凭证与基础信息」页面获取 App ID 和 App Secret
3

配置事件订阅

在「事件订阅」中添加 im.message.receive_v1 事件，设置请求地址为 PAI 的 Webhook 端点
4

配置权限

在「权限管理」中开通以下权限：
  • im:message — 发送消息
  • im:message.receive — 接收消息
  • im:resource — 上传图片等资源
5

发布应用

完成配置后发布应用，等待管理员审批

​
环境变量配置

​
FEISHU_APP_ID
string
required
飞书应用的 App ID
​
FEISHU_APP_SECRET
string
required
飞书应用的 App Secret
​
FEISHU_VERIFICATION_TOKEN
string
required
事件订阅的 Verification Token，用于验证请求来源
​
FEISHU_ENCRYPT_KEY
string
事件订阅的 Encrypt Key。如果在飞书后台配置了加密，则需要填写此项
​
FEISHU_RECEIVE_ID_TYPE
string
default:"open_id"
消息接收者 ID 类型，可选值：open_id、user_id、union_id、email、chat_id
FEISHU_APP_ID=cli_xxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxxxxxxxxxx
FEISHU_RECEIVE_ID_TYPE=open_id

​
Webhook 配置

端点： POST /webhook/feishu

​
URL 验证握手

飞书在配置事件订阅时会发送一个验证请求，PAI 会自动处理此握手： 
// 飞书发送的验证请求
{
  "challenge": "ajls384kdjx98XX",
  "token": "xxxxxx",
  "type": "url_verification"
}

// PAI 返回的响应
{
  "challenge": "ajls384kdjx98XX"
}
URL 验证是一次性的。配置完成后，飞书会通过相同端点推送实际的消息事件。

​
Token 管理

飞书 API 调用需要 tenant_access_token，PAI 会自动管理 Token 的获取和缓存：
  1. 首次调用时，使用 App ID 和 App Secret 换取 tenant_access_token
  2. Token 会被缓存，避免重复请求
  3. Token 过期前自动刷新
开发者无需手动处理 Token 生命周期。

​
功能支持与限制

当前仅支持单聊（P2P）对话，群聊消息暂不处理。

​
文本消息

支持接收和发送文本消息，完整的 AI 对话能力。

​
图片消息

飞书的图片处理采用特殊的上传流程：
1

生成图片

AI 处理产生需要发送的图片数据（二进制格式）
2

上传到飞书

调用飞书图片上传 API，将二进制图片数据上传到飞书服务器
3

获取 image_key

飞书返回 image_key，这是图片在飞书系统中的唯一标识
4

发送图片消息

使用 image_key 构造图片消息并发送给用户
图片二进制数据 → 飞书图片上传 API → image_key → 发送图片消息

​
消息处理流程

飞书用户发送单聊消息
    │
    ▼
飞书服务器推送事件到 POST /webhook/feishu
    │
    ▼
验证 Verification Token（+ 解密 Encrypt Key）
    │
    ▼
解析为 UnifiedMessage(platform_id="feishu", content=..., image_urls=[...])
    │
    ▼
AI 核心管线处理
    │
    ▼
UnifiedSender → 飞书发消息 API（使用 tenant_access_token）→ 用户收到回复