跳到主要内容

飞书对接指南

将 Sage AI 接入飞书企业自建应用（机器人）后，员工可在飞书私聊或群聊中与 AI 对话。

本期飞书配置表单仅提供 URL 回调（Webhook）。飞书开放平台事件订阅须选择 「将事件发送至开发者服务器」，并回填平台生成的 Webhook。

配置 IM 渠道可将 Sage AI 对话接入团队 IM，实现即时问答与协作。机器人自动绑定当前资源域并遵循权限管控，如需访问全部权限数据，可前往「全部资源域」配置。请勿在不同账号、环境或资源域中重复绑定同一 IM 凭证，否则可能导致消息丢失或对话中断。

先决条件​

要求说明
功能菜单具备 AI 工作台 / 安全运营 / IM 渠道 菜单权限
操作权限配置、解绑需读写权限
飞书账号具备创建企业自建应用、机器人开发权限
网络平台需提供公网可访问的 HTTPS Webhook
模型至少配置一个可用推理模型；IM 侧默认 Auto
说明

本期飞书对接仅支持 URL 回调。企业微信、钉钉仍同时支持长连接与 URL 回调，详见各自对接指南。

整体流程（一览）​

1. 新建企业自建应用并开启机器人能力
        ↓
2. 批量开通消息、卡片等相关权限
        ↓
3. 获取 App ID / App Secret / Encrypt Key（Verification Token 选填）
        ↓
4. 在 AI 工作台填写并保存，复制 Webhook
        ↓
5. 飞书事件订阅选择「将事件发送至开发者服务器」，填入 Webhook
        ↓
6. 添加「接收消息」事件；配置「卡片回传交互」
        ↓
7. 创建版本并发布 → 私聊 / 群聊测试

一、创建飞书应用​

1. 登录并创建​

访问 飞书开放平台，点击 「创建企业自建应用」：

创建企业自建应用

2. 填写应用信息​

配置项说明
应用名称如「Sage AI 助手」
应用描述简要说明用途
应用图标上传图标

image-20260821175136043

创建成功后进入应用详情：

应用详情

3. 添加机器人能力​

在「添加应用能力」中找到 机器人，点击 添加：

image-20260821175208940

二、配置应用权限​

进入 权限管理 → 批量导入 / 导出权限：

image-20260821175229519

image-20260821175249085

  1. 清空输入框。
  2. 粘贴下方权限 JSON（可按企业安全策略裁剪，但须保留消息收发与卡片相关权限）。
  3. 点击 确定新增权限。
{
  "scopes": {
    "tenant": [
      "contact:contact.base:readonly",
      "docx:document:readonly",
      "im:chat:read",
      "im:chat:update",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message.pins:read",
      "im:message.pins:write_only",
      "im:message.reactions:read",
      "im:message.reactions:write_only",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "im:message:send_multi_users",
      "im:message:send_sys_msg",
      "im:message:update",
      "im:resource",
      "application:application:self_manage",
      "cardkit:card:write",
      "cardkit:card:read"
    ],
    "user": [
      "contact:user.employee_id:readonly",
      "offline_access",
      "im:chat.members:read",
      "im:chat:read",
      "im:message",
      "im:message.group_msg:get_as_user",
      "im:message.p2p_msg:get_as_user",
      "im:message:readonly"
    ]
  }
}

三、获取应用凭证与加密参数​

1. App ID / App Secret​

凭证与基础信息：

凭证与基础信息

重要

请妥善保管 App Secret。

2. Encrypt Key / Verification Token​

进入 事件与回调 → 加密策略：可刷新生成或自定义。

Encrypt Key

image-20260821175335458

建议填写 Encrypt Key；Verification Token 在 AI 工作台为选填。Encrypt Key 留空则不开启消息加密。

四、在 AI 工作台配置飞书（URL 回调）​

  1. 进入 AI 工作台 → 安全运营 → IM 渠道 → 飞书 → 配置。
  2. 连接方式固定为 使用 URL 回调（Webhook）（无长连接选项）。
  3. 填写字段并 保存，复制生成的 Webhook。
字段是否必填说明默认值校验规则
App ID必填飞书应用 App ID无非空；≤1000；不脱敏
App Secret必填应用密钥无非空；≤1000；脱敏
Encrypt Key建议填写事件加密；留空则不开启加密（以产品为准）无≤1000；脱敏
Verification Token选填事件校验 Token无≤1000；脱敏

image-20260821175411000

保存时校验 App ID / Secret，通过后为「已连接」并生成 Webhook。

会话管理：自动开启新会话，默认 24 小时（1–24，不可关闭）。

点击 「解绑」 并二次确认后解除绑定。

五、配置飞书事件与卡片回调​

1. 事件订阅（URL 回调）​

返回飞书开放平台 → 事件与回调，订阅方式选择 「将事件发送至开发者服务器」（不要选择长连接接收事件），粘贴 AI 工作台生成的Webhook 并保存：

image-20260821175742956

2. 添加「接收消息」事件​

在「事件配置」中 添加事件，搜索并添加 接收消息：

image-20260821175810772

3. 配置应用卡片回调（保留能力）​

  1. 切换到 回调配置 页签。
  2. 搜索并添加 卡片回传交互。

image-20260821175831805

应用卡片

未开通卡片权限或未配置「卡片回传交互」时，卡片按钮可能无响应。

六、发布应用​

image-20260821175914702

配置可用范围后，等待审批通过（管理员通常自动通过）。

七、开始使用​

image-20260821180023629

发送「你好」验证连通；需确认的操作按卡片提示点击。

项说明
模型Auto 路由
资源范围绑定账号 + 资源域下「我的」可用资源
限流同一机器人约 1 分钟 ≤ 20 次提问

八、常见问题​

机器人没有响应？​

  1. 确认应用已发布且在可用范围内。
  2. 确认 AI 工作台与飞书均为 URL 回调，且 Webhook 已保存。
  3. 确认飞书订阅方式不是「长连接接收事件」。
  4. 确认已添加「接收消息」与「卡片回传交互」。
  5. 核对 App ID / App Secret / Encrypt Key。

相关文档​