飞书
接入飞书后,成员可以用飞书一键登录,也可以在飞书群里 @Bot、或在飞书里单聊 Bot 的应用来使用它们。本页说明系统管理员在「飞书」页要做的配置,以及飞书开发者后台的配置清单。

需要哪些应用
| 应用 | 数量 | 在哪里接入 | 用途 |
|---|---|---|---|
| 主应用 | 全系统 1 个 | 管理后台 · 飞书 | 飞书登录;把成员在共工里发给 Bot 的消息同步到飞书;列出可关联的飞书群、同步群成员 |
| Bot 应用 | 每个 Bot 1 个 | Bot 设置的「飞书」页(Bot 主人或系统管理员),或本页的 Bot 表 | 在飞书群里接收 @它 的消息、在飞书里单聊,以它自己的身份回复、发运行卡片和提问/审批卡片 |
都必须是企业自建应用,一个应用只能接入给主应用或一个 Bot。没有接入主应用时,飞书联动整体不可用,登录页也不显示飞书按钮,群设置里也不能关联飞书群。
主应用在飞书里显示为一个机器人,成员看到的文案里叫「共工机器人」(有显示名时写作「「显示名」机器人」)。「主应用」「Bot 应用」只在管理后台和本文档里出现。
三个词
- 飞书应用和共工之间叫接入 / 移除;
- 共工群和飞书群之间叫关联 / 取消关联;
- 共工账号和飞书账号之间叫绑定 / 解绑。
页面内容
「飞书」页从上到下:
- 接入进度:四步——对外地址 → 接入主应用 → 审核通过 → 成员可用,每步和下面表单用同一个判定。四步都完成后收成一行「飞书已接通 · N 人已绑定飞书账号」。
- 对外地址:浏览器访问共工的地址,如
https://gonggong.example.com,点「保存」生效。为空时自动预填当前网址,并提示「尚未保存,预填的是当前网址」,「保存」为主按钮。飞书卡片里的链接、飞书登录回调和进群卡片都基于它,所以保存对外地址之前「扫码创建或接入」是禁用的。保存后下方显示要在飞书后台添加的「重定向 URL」。 - 主应用 · 凭证:未接入时显示扫码和手动填写;接入后收起为一行状态(未接入 / 连接中 / 等待审核 / 待确认 / 连接失败 / 已接通)和 App ID,下面是接入进度清单(见下文),按钮只剩「更新权限」「更换应用…」「移除主应用」。重新扫码会替换当前应用,所以要先点「更换应用…」才展开扫码和手动填写。
- Bot:各 Bot 的飞书状态(未接入 / 连接中 / 等待审核 / 连接失败 / 已接通)和原因;行末「操作」里可以直接接入、更新权限或重试。默认只列已接入的,点「显示全部」看全部 Bot。
- 飞书群:已关联飞书群的共工群、所属团队、飞书群名、关联时间、Bot 入群情况和最近一次失败原因;你在群里时可以「打开群」。入群情况要实时问飞书,这里显示「—」,到群设置 · 飞书里看实时值;失败原因只包含服务启动以来记录到的。
- 账号 · 飞书自动开户:见下文 账号。
接入应用
主应用在本页接入,Bot 应用在 Bot 设置的「飞书」页接入,步骤相同。可以接入新应用,也可以接入飞书开发者后台里已有的应用。
方式一:扫码创建或接入(推荐)
- 点「扫码创建或接入」(已接入过应用时先点「更换应用…」),用飞书扫码(或点「在飞书中打开」)。二维码有倒计时(如「9:58 后过期」),过期后点「重新生成」。
- 在飞书确认页里选择新建应用或选择已有应用,确认共工预填的权限、事件和回调。
- 确认后共工保存凭证、建立长连接,并尝试自动完成开发配置:把事件与回调设为长连接方式,给主应用加上重定向 URL。
扫码成功后窗口不会自动关闭,而是显示还差哪几步:
| 项 | 说明 |
|---|---|
| 已保存并连上飞书 | 长连接已连上 |
| 飞书管理员已审核通过 | 新应用的首个版本要企业飞书管理员审核。审核通过前自动配置一定失败,共工以此判断;显示「等待企业飞书管理员审核,通过后自动完成,无需回来操作」,也可以点「重试」。不是在飞书开发者后台创建的应用判断不了,会提示去开发者后台确认已发布 |
| 成员可以使用 | 飞书不告诉共工应用的可用范围,所以这一项始终是提醒:新应用默认只有创建者可用,请在飞书管理后台把可用范围改为需要的成员 |
同一份清单也常驻在应用设置里,连上且审核通过后收成一行「已接通」。
已接入的应用如果缺少权限(比如共工升级后需要新权限),点「更新权限」重新扫码确认即可补齐。
方式二:手动填写凭证
- 在 飞书开发者后台 打开应用,在「凭证与基础信息」里复制 App ID 和 App Secret。
- 在「或手动填写已有应用的凭证」下填入,点「接入」。共工会先向飞书校验凭证,通过后建立长连接,再尝试自动完成开发配置。更换凭证时点「更换应用…」,填入新的 App ID 和 App Secret 后点「更换」。
- 如果自动配置失败,通常是应用还没有
application:application:patch权限,或新权限还没审核通过。可以点「更新权限」扫码一次补齐(推荐),或按下面的清单在飞书开发者后台手动配置后在清单里点「重试」。
自动配置失败时,共工每分钟会自动重试一次,飞书管理员审核通过后会自动完成。
「移除」只断开共工与该应用的长连接,飞书开发者后台中的应用不受影响。
为什么不直接读审核状态和可用范围
飞书有读取应用版本和可用范围的接口,但读版本要 application:application:self_manage,这个权限同样要首个版本审核通过后才生效,审核前读不到,和「自动配置是否成功」的判断结果一样;读可用范围要 admin:app.info:readonly,是需要企业管理员审批的高级权限。所以共工用「自动配置是否成功」判断审核,用「除接入人外是否还有人绑定了飞书账号」判断成员可用。
飞书开发者后台配置清单
扫码方式会自动填好这些项。手动配置或排查问题时请逐项核对。
应用能力
主应用和 Bot 应用都要在「添加应用能力」中开启机器人。
权限
在「权限管理」中开通:
| 应用 | 身份 | 权限 |
|---|---|---|
| 主应用 | 应用身份 | im:message:send_as_bot、im:chat:readonly、im:chat.members:write_only、im:chat:create、im:resource、im:message.reactions:write_only、cardkit:card:write、application:application:patch |
| 主应用 | 用户身份 | offline_access、contact:user.email:readonly、contact:user.employee_id:readonly、im:message、im:message.send_as_user、im:message.group_msg:get_as_user |
| Bot 应用 | 应用身份 | im:message.group_at_msg:readonly、im:message.p2p_msg:readonly、im:message:send_as_bot、im:message:readonly、im:chat:readonly、im:resource、im:message.reactions:write_only、cardkit:card:write、application:application:patch |
事件与回调
先在共工里接入,确认状态为「已连接」后再配置。飞书要求保存长连接方式时应用已经连上。
- Bot 应用:
- 「事件与回调 · 事件配置」:订阅方式选使用长连接接收事件,添加
im.message.receive_v1(接收消息)和im.message.recalled_v1(消息撤回)。 - 「事件与回调 · 回调配置」:订阅方式选使用长连接接收回调,添加
card.action.trigger(卡片回传交互)。
- 「事件与回调 · 事件配置」:订阅方式选使用长连接接收事件,添加
- 主应用只订阅事件(长连接),不需要回调:
im.message.receive_v1、im.message.recalled_v1:群设置 · 飞书「飞书 → 共工」选「同步全部消息」时,接收飞书群里的消息。im.chat.member.user.added_v1、im.chat.member.user.deleted_v1、im.chat.member.user.withdrawn_v1:用户进出飞书群,用于同步群成员。im.chat.member.bot.added_v1:主应用被拉进飞书群时,在未关联的飞书群里发「接入共工」卡片。
共工通过长连接接收事件,服务器不需要公网回调地址。
重定向 URL(仅主应用)
在「安全设置 · 重定向 URL」中添加 <对外地址>/api/auth/feishu/callback。填好对外地址后,「飞书」页会直接显示这个地址。
发布版本
修改权限或能力后,要在「版本管理与发布」中创建版本并发布,经企业飞书管理员审核通过后才生效。
账号
「飞书自动开户」默认开启:本企业成员第一次飞书登录时,可以直接新建共工账号,不受「开放自助注册」限制。关闭后只能绑定已有账号,或者凭邀请注册。成员也可以在个人设置里绑定或解绑飞书账号。
在飞书群里使用 Bot
飞书群的关联由群管理员在共工的「群设置 · 飞书」里完成,最顺的路径是从飞书群出发:
- 在飞书群设置 › 群机器人里添加共工机器人。
- 群里会出现一张「接入共工」卡片(需要先保存对外地址;没有对外地址时卡片只提示去群设置里关联)。点开后二选一:
- 新建共工群:以飞书群名新建共工群并关联,已绑定飞书账号的本团队成员和已在群里的 Bot 一起加入;
- 关联到已有群:选一个你是管理员、还没关联飞书群的群。
- 也可以在共工里操作:「群设置 · 飞书」顶部先确认两项前置条件——「绑定你的飞书账号」(已绑定显示「已绑定」,没绑定直接点「绑定飞书账号」)和「把共工机器人拉进飞书群」(已有可关联的群时显示「已在群中」,否则可复制机器人名);然后在「选择飞书群」里选一个飞书群点「关联」(只列出机器人和你都在、尚未关联的飞书群);没有现成的飞书群时,在「没有现成的飞书群」里点「创建飞书群」。一个共工群只能关联一个飞书群。
- 关联后,「群里的 Bot」列出各 Bot 的状态:没进群的点「拉入飞书群」;没有飞书应用的 Bot,Bot 主人或系统管理员会看到「去接入」,直接打开该 Bot 设置的飞书页,其他人看到「请 Bot 主人接入」。
- 之后成员在飞书群里 @Bot 就能触发运行。成员需要先绑定飞书账号,并且是对应共工群的成员。不是群成员的人 @Bot 时,如果这个群归入了团队分区、他也在这个团队里,提醒卡片会带「申请加入」。
关联后的同步设置按方向分组:
- 共工 → 飞书:「网页消息发到飞书群」开关。
- 飞书 → 共工:「只同步 @Bot 的消息 / 同步全部消息」二选一。
另外还有「同步飞书群成员」和「改为飞书群名」。
主应用调用飞书失败(如 App Secret 被重置、飞书不可达)时,已关联的群顶部显示「飞书调用失败」和原因,同步设置和「取消关联」照常可用;系统管理员另有「去管理后台检查飞书」。拉 Bot 失败时只弹出「没能拉入,原因见列表」,原因写在该 Bot 一行里。
常见问题
| 现象 | 处理 |
|---|---|
| 状态为「连接失败」 | 检查 App Secret 是否被重置,服务器能否访问 open.feishu.cn |
| 提示未设置对外地址 | 先在「飞书」页保存对外地址,再在接入清单里点「重试」 |
| 一直显示「等待企业飞书管理员审核」 | 请企业飞书管理员在飞书管理后台审核应用的首个版本,通过后一分钟内自动完成 |
| 别人飞书登录报 20010 | 应用可用范围只有创建者,请在飞书管理后台把可用范围改为需要的成员 |
| 飞书群里 @Bot 没反应 | 检查 Bot 应用是否「已连接」、是否已在群中,事件 im.message.receive_v1 是否以长连接方式订阅,版本是否已发布 |
| 卡片按钮点了无效 | 检查 Bot 应用的回调 card.action.trigger 是否以长连接方式配置 |
| 飞书登录后报重定向错误 | 检查重定向 URL 是否与对外地址一致 |