← 返回通道

飞书通道配置指南

在飞书开放平台创建并配置机器人后，即可在通道页使用飞书长连接与机器人对话。

一、创建应用

  1. 打开 飞书开放平台，使用企业管理员或开发者账号登录。
  2. 点击 「创建企业自建应用」。
  3. 填写应用名称、描述，选择应用图标，创建应用。

说明：飞书长连接模式仅支持 企业自建应用，不支持应用商店应用。

二、启用机器人能力

  1. 在应用详情页左侧进入 「机器人与消息」。
  2. 开启 「启用机器人」。
  3. 根据需要配置机器人名称、描述、头像等。

三、配置事件订阅（长连接）

  1. 在应用详情页左侧进入 「事件与回调」。
  2. 在「事件配置」区域，选择订阅方式：「使用长连接接收事件」（不要选「请求地址」）。
  3. 点击「添加事件」，在事件列表中勾选 「接收消息」（事件类型：im.message.receive_v1）。
  4. 保存配置。

注意：保存前请确保本系统「通道」页中的飞书卡片已点击「连接」并保持长连接在线，否则飞书后台可能保存失败。

四、配置权限并导入

  1. 在应用详情页左侧进入 「权限管理」。
  2. 在「权限配置」中，点击 「导入权限配置」 或 「批量导入」（以飞书后台实际入口为准）。
  3. 将下面框中的 JSON 配置完整复制，粘贴到飞书后台的导入框中并确认导入。
{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:contact.base:readonly",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "docs:document.content:read",
      "event:ip_list",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "contact:contact.base:readonly",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}
  1. 导入后，在权限列表中确认所需权限已勾选（尤其是 im:message、im:message:send_as_bot、im:message:readonly 等与消息收发相关的权限）。
  2. 如有「申请权限」或「提交审核」步骤，按飞书要求完成。

五、获取凭证

  1. 在应用详情页左侧进入 「凭证与基础信息」。
  2. 在「应用凭证」区域查看 App ID 与 App Secret，复制后填入本系统通道页飞书卡片的对应输入框。
  3. 请勿将 App Secret 泄露给他人或提交到公开代码库。

六、发布与使用

  1. 若企业要求「先发布后使用」，请在应用详情页完成「版本管理与发布」，将应用发布到企业。
  2. 在本系统打开 通道 页，在飞书卡片中填入 App ID 与 App Secret，点击「连接」，等待状态变为「已连接」。
  3. 在飞书客户端（群聊或单聊）找到该机器人并发送消息，即可与机器人对话。

常见问题

  • 保存事件配置失败：请先在本系统飞书卡片点击「连接」，保持长连接在线后再在飞书后台保存。
  • 收不到消息 / 无法回复：检查权限中是否已开通 im:message:readonly、im:message:send_as_bot 等，并确认事件中已添加 im.message.receive_v1。
  • token 错误：在通道页连接前，请先在本系统完成登录，以便使用当前用户 token 调用对话接口。