跳到主要内容

飞书渠道配置指南

飞书渠道可以把一个 AskTable 智能体连接到飞书机器人。配置完成后，用户可以在飞书单聊或群聊中向机器人提问，AskTable 会把飞书消息转成智能体对话，并将智能体回复发送回飞书。

适用场景​

  • 希望业务人员直接在飞书中查询数据、追问分析结果。
  • 希望把已经配置好的 AskTable 智能体接入企业 IM。
  • 私有部署环境需要用飞书机器人提供内部数据问答入口。

当前飞书渠道以文本对话为主。图片、文件、语音等非文本消息不会进入智能体处理流程。

工作方式​

AskTable 的飞书接入由 Feishu Gateway 服务完成。它不保存业务数据，也不执行智能体逻辑，只负责飞书长连接和 AskTable Server 之间的消息转发。

飞书用户
  |
  | 发送文本消息
  v
飞书开放平台
  |
  | 长连接事件 im.message.receive_v1
  v
Feishu Gateway
  |
  | Redis: at:channel:inbound / at:channel:outbound:feishu
  v
AskTable Server
  |
  | 调用绑定的 AskTable 智能体
  v
Feishu Gateway
  |
  | 飞书消息回复 API
  v
飞书用户
信息

Feishu Gateway 使用飞书开放平台的长连接能力，不需要在飞书后台配置公网 Webhook 请求地址。

前提条件​

开始配置前，请确认：

  1. AskTable 已完成部署，并且可以正常登录控制台。
  2. 需要接入飞书的 AskTable 智能体已经创建完成。
  3. 私有部署环境已启用 asktable_feishu_gateway 服务。
  4. 你拥有飞书开放平台中创建和配置企业自建应用的权限。
  5. 你拥有 AskTable 项目的管理员权限，可以编辑智能体渠道配置。

第一步：启用 Feishu Gateway​

如果使用 AskTable 的 Docker Compose 部署，飞书网关服务在部署文档中默认标注为选填。需要飞书 IM 接入时，取消相关注释并启动服务。

asktable_feishu_gateway:
  image: registry.cn-shanghai.aliyuncs.com/datamini/asktable-feishu-gateway:latest
  # image: datamini/asktable-feishu-gateway:latest
  container_name: asktable_feishu_gateway
  restart: unless-stopped
  depends_on:
    - asktable_redis
  environment:
    TZ: Asia/Shanghai
    REDIS_URL: redis://asktable_redis:6379

然后重新启动服务：

docker compose up -d

可用以下命令检查网关日志：

docker logs -f asktable_feishu_gateway

看到类似 Feishu Gateway running 的日志，表示网关进程已启动。真正连通飞书还需要完成后续应用凭证和事件配置。

第二步：创建飞书企业自建应用​

  1. 打开 飞书开放平台。
  2. 选择企业，创建「企业自建应用」。
  3. 填写应用名称、描述和图标。建议名称能让用户识别这是 AskTable 数据助手。
  4. 创建完成后，进入应用详情页。

第三步：获取应用凭证​

在飞书应用详情页进入「凭证与基础信息」，复制以下字段：

字段是否必填用途
App ID必填AskTable 用它识别飞书应用
App Secret必填AskTable 用它连接飞书长连接并调用回复接口
注意

App Secret 是敏感信息，只应填写到 AskTable 的飞书渠道配置中，不要发送到群聊、工单或公开文档。

第四步：配置机器人能力和权限​

在飞书应用后台完成以下配置：

  1. 进入「应用能力」，启用机器人能力。
  2. 进入「权限管理」，添加消息相关权限。
  3. 至少需要允许应用接收用户发送给机器人的消息，并以机器人身份回复消息。
  4. 保存后发布应用版本，并等待企业管理员审批通过。

飞书开放平台的权限名称可能会随版本调整。配置时请以飞书后台实际展示为准，重点确认应用具备以下能力：

  • 接收机器人单聊或群聊中的消息事件。
  • 以机器人身份发送或回复消息。

第五步：订阅消息事件​

AskTable 当前使用飞书长连接模式接收事件。请在飞书应用后台进入「事件与回调」或「事件订阅」相关页面：

  1. 选择长连接或事件订阅能力。
  2. 订阅 im.message.receive_v1 事件。
  3. 如果飞书后台要求填写 Encrypt Key 或 Verification Token，复制这两个值，后续填入 AskTable；如果未启用加密或页面没有要求，可以留空。
  4. 发布应用版本，确保新权限和事件订阅生效。
备注

不需要为 AskTable Feishu Gateway 配置 https://.../callback 形式的请求地址。网关会主动通过飞书长连接接收事件。

第六步：在 AskTable 中配置飞书渠道​

  1. 登录 AskTable 控制台。
  2. 进入需要接入飞书的项目。
  3. 打开目标智能体的编辑页面。
  4. 切换到「频道」页签。
  5. 开启「飞书」渠道。
  6. 填写飞书应用凭证。
配置项是否必填说明
App ID新建时必填飞书应用的 App ID
App Secret新建时必填飞书应用的 App Secret
Encrypt Key可选飞书事件加密密钥。启用事件加密时填写
Verification Token可选飞书事件验证 Token。飞书后台要求校验时填写
  1. 点击保存。
  2. 在同一页面查看运行状态，必要时点击刷新。

状态显示为「已连接」后，说明 AskTable Server 已把渠道配置同步到 Feishu Gateway，且网关已经建立飞书连接。

第七步：在飞书中安装和测试​

  1. 在飞书应用后台发布应用版本，并确保企业管理员已审核通过。
  2. 将应用安装到企业或指定用户范围。
  3. 在飞书中找到机器人，发起单聊测试。
  4. 如果要在群聊中使用，将机器人添加到目标群。
  5. 发送一个文本问题，例如：
    • 「本周新增了多少客户？」
    • 「昨天销售额最高的门店是哪家？」
    • 「帮我分析一下最近 7 天订单量变化。」

AskTable 会为同一飞书发送者和同一渠道保持一段会话上下文。用户连续追问时，智能体会沿用之前的对话上下文。

验证与排查​

渠道一直显示未连接​

请依次检查：

  1. asktable_feishu_gateway 容器是否正在运行。
  2. Feishu Gateway 的 REDIS_URL 是否指向 AskTable 使用的同一个 Redis。
  3. AskTable Server 是否能访问同一个 Redis。
  4. App ID 和 App Secret 是否填写正确。
  5. 飞书应用是否已发布并通过企业管理员审批。
  6. 是否已订阅 im.message.receive_v1 事件。

飞书能收到消息，但 AskTable 没有回复​

请检查：

  1. 飞书应用是否具备机器人回复消息所需权限。
  2. 用户发送的是否是文本消息。
  3. 绑定的 AskTable 智能体是否能在 AskTable 控制台中正常对话。
  4. Feishu Gateway 日志中是否有 outbound 或 reply API 错误。

群聊中没有响应​

请检查：

  1. 机器人是否已添加到该群。
  2. 群内是否允许机器人接收消息。
  3. 飞书应用的可用范围是否包含该群成员。
  4. 权限和事件订阅变更后，应用是否重新发布并审批。

修改凭证后没有生效​

在 AskTable 智能体的「频道」页签重新保存飞书配置，然后刷新连接状态。必要时重启 asktable_feishu_gateway 容器，让网关重新加载渠道配置。

相关文档​