跳转到主要内容
版本要求:所有版本均可创建 IM 应用用于 AI SRE 对话;将应用用于 On-call 分派通知,需有效的 On-call 专业版订阅。了解更多

选择接入方式

新建飞书集成时有三种接入方式,区别在于飞书应用由谁来建、后续配置由谁做: 私有化部署的 Flashduty 连不到飞书扫码接口,只能用 手动填写凭证。

扫码创建并自动托管(推荐)

  1. 新建飞书集成时,飞书应用授权 默认选中 创建新应用(推荐)。填好名称后点击 保存,页面弹出二维码。
  2. 用飞书扫一扫确认:飞书确认页会列出要申请的权限,点 创建 即可。确认之前 Flashduty 不保存任何记录。
  3. 扫码确认后,Flashduty 在您的飞书企业里创建应用(默认名称 Flashduty),并提交第一次审批。应用要收发消息、读群消息,飞书规定由企业管理员审核通过后才能使用。
  4. 第一次审批通过后,Flashduty 自动完成全部配置:生成事件与回调加密策略用的 Encrypt Key 和 Verification Token;添加网页端和移动端的登录重定向 URL;把可用范围设为全部成员(仅首次配置时设置,后续版本保留管理员改过的范围);补齐已开启功能需要的权限,以及 application:application:self_manage、application:application:patch 两项自管理权限(让 Flashduty 之后能自己更新配置、发布版本,不用再扫码);把事件和回调都指向 Flashduty 的请求地址(事件 im.message.receive_v1,回调 card.action.trigger);开启 网页应用 与 机器人 能力,工作台默认打开 Flashduty 网页应用。配置完发布一个新版本,等管理员审批配置版本。
  5. 两次审批都通过后,集成即可使用。若飞书没有接受版本里的默认打开方式,Flashduty 会再提交一个小版本补上,审核期间不影响使用。
审核中详情页每 10 秒自动向飞书核对一次结果;也可以点 复制消息给管理员,把要审批的内容发给飞书管理员,或点 去飞书管理后台审核 直接打开飞书管理后台的应用审核页。 托管应用的凭证由 Flashduty 生成和保管,页面只显示 App ID、当前版本 和 状态,编辑页会提示「飞书应用 xxx 由 Flashduty 自动管理,凭证由 Flashduty 保管,不需要填写」。这些凭证由 Flashduty 保管,不需要也无法在 Flashduty 里修改。

使用已有应用

在 飞书应用授权 里选 使用已有应用,填入应用的 App ID,点击 保存 后用应用所有者或协作者的飞书账号扫码,授权 Flashduty 管理这个应用。之后的两次审批和自动配置与创建新应用相同。已被其他 Flashduty 账户使用的 App ID 会被拒绝。

托管应用的状态与处理

集成详情页和集成列表都会显示托管应用的状态。 已生效的集成,Flashduty 每 10 分钟核对一次凭证;Secret 被重置、应用被停用或删除时会自动变成上面的状态。开启需要额外权限的功能(例如作战室复盘导入群聊记录、在飞书里使用 AI SRE)后,详情页会出现「已开启的功能需要追加 N 项飞书权限」的提示,点 提交给飞书管理员审核 后 Flashduty 自动给应用加上权限并发布新版本,不需要重新扫码。

创建飞书应用

以下步骤只适用于 手动填写凭证 接入(含 Lark 国际版与私有化部署)。扫码创建或已升级为自动管理的集成由 Flashduty 完成这些配置,不需要手工执行。

1. 创建自建应用

访问 飞书开发者后台,创建企业内自建应用。应用图标可使用 Flashduty 官方 icon。 详见飞书开发文档 创建企业自建应用。 飞书/Lark:创建自建应用 界面截图

2. 复制凭证信息

前往 凭证与基础信息 页面,复制 App ID 和 App Secret 备用。 飞书/Lark:复制凭证信息 界面截图

3. 复制事件回调的 Token 信息

前往 开发配置 → 事件与回调 → 加密策略 页面,生成并复制 Encrypt Key(推荐启用,更安全;飞书里没设就留空)和 Verification Token 备用。 飞书/Lark:复制事件回调的 Token 信息 界面截图

添加飞书集成

回到 Flashduty On-call 集成中心 页面,选择 即时消息 → 飞书,在 飞书应用授权 里点 改为手动填写凭证(新建时默认是扫码授权;私有化部署和编辑已有集成时直接就是凭证表单),然后在表单中填入 名称 以及上一步复制的 App ID、App Secret、Verification Token 和 Encrypt Key 后,点击 保存 完成创建。保存时系统会用 App ID 和 App Secret 向飞书换一次访问凭证,填错会直接提示。 如果您使用的是 Lark(国际版),请同时开启 是否为 Lark 版本 开关,开启后系统将使用 Lark 国际版端点进行通信。Lark 开放平台的开发者后台入口为 open.larksuite.com,上文创建应用、配置权限等步骤均在该站点完成。 创建成功后,您将在列表中看到已添加的飞书集成。点击其名称进入详情页,详情页会给出编号 5 步的接入向导,每一步都提供可直接复制的地址或权限清单,编号与下文「在飞书完成配置」一致。 飞书/Lark:添加飞书集成 界面截图

在飞书完成配置

详情页的 在飞书完成配置 把剩下的工作拆成编号 5 步,每一步对应飞书开发者后台的一个页面,编号与本节一致,标题右侧显示「N / 5 已完成」。权限开通和请求地址校验发生在飞书那边,切回详情页时会自动重新读一次(也可以点 重新检测):飞书会校验请求地址,所以第 3 步能自动打勾;飞书不回传应用能力、重定向 URL 和版本发布,这三步做完后请点按钮手动确认。手动确认需要集成的编辑权限,没有权限的成员只能看状态。

1. 开通权限

进入 权限管理 页面,点「批量处理 › 批量导入/导出权限」,粘贴详情页第 1 步 复制权限清单(N 项) 复制的权限清单,点「下一步,确认新增权限」后确认开通。清单是飞书批量导入接受的 JSON,形如 {"scopes":{"tenant":[...],"user":[]}},内容是下表全部权限。 下表权限覆盖基础通知、作战室、AI SRE 对话和 AI 生成复盘。请特别确认已开通 im:message.p2p_msg:readonly 和 im:message.group_at_msg:readonly,否则飞书不会向 Flashduty 推送单聊消息或群聊 @ 机器人消息。开启 允许 AI 主动接话 时,还必须确认 im:message.group_msg 已开通,并在事件与回调中订阅 im.message.receive_v1;否则飞书只会推送 @ 机器人消息。im:message.reactions:write_only 用于主动接话决定回复后的 ACK 表情。权限或事件配置变更后,需要重新发布应用后才会在线上生效。 三组权限的用途:「基础」是告警通知、卡片按钮、关联成员和作战室所必需;「作战室复盘」只在复盘要导入群聊记录时需要;「AI SRE」只在飞书里使用 AI SRE 时需要。 这一步由平台自动检测:基础 一组全部开通就算完成,显示「基础 N 项已开通」,缺权限时显示「缺 N 项基础权限」;后两组按需开通,不影响打勾。 飞书/Lark:申请应用权限 界面截图

2. 添加网页应用和机器人

  1. 回到飞书开发者后台,进入刚才创建的飞书应用,进入 添加应用能力 → 按能力添加 页面,同时开通 网页应用 和 机器人 能力。 飞书/Lark:开通并配置应用能力 界面截图
  2. 前往 网页应用 页面,配置 桌面端主页 和 移动端主页,内容均为详情页第 2 步给出的地址。详见飞书开发文档 配置应用主页地址。 飞书/Lark:开通并配置应用能力 界面截图
应用图标可使用 Flashduty 官方 icon,在 凭证与基础信息 页面上传。飞书不回传应用能力配置,完成后在详情页第 2 步点 我已添加 确认。

3. 配置事件与回调

事件和回调用同一个请求地址,内容为详情页第 3 步给出的地址。飞书保存请求地址时会立刻访问这个地址做校验。
  1. 前往 事件回调 → 事件配置 页面,订阅方式选「将事件发送至开发者服务器」,粘贴请求地址并保存。然后添加事件 im.message.receive_v1。 飞书/Lark:开通并配置应用能力 界面截图
  2. 切到 回调配置 页面,同样粘贴请求地址并保存,再添加回调 card.action.trigger。 飞书/Lark:开通并配置应用能力 界面截图
飞书校验通过后这一步自动打勾(显示 已通过校验),还没收到校验时显示 等待飞书校验。如果飞书提示「请求地址校验失败」,多半是新建集成时填的 Verification Token 或 Encrypt Key 和飞书「加密策略」页不一致,到集成编辑页改成一致后重新保存。

4. 配置重定向 URL

进入 安全设置 页面,在 重定向URL 下添加详情页第 4 步给出的两条地址:网页端 …/login 和移动端 …/login。飞书不回传这项配置,完成后在详情页第 4 步点 我已添加 确认。 详见飞书开发文档 配置重定向 URL。 飞书/Lark:添加重定向 URL 到飞书应用 界面截图

5. 调整可见范围并发布

打开 版本管理与发布 页面,创建版本,将 可用范围 选为「全部员工」,提交发布(企业管理员审核通过后生效)。第 1–4 步的改动都要发布后才生效;之后再改权限、事件或回调,要再发一个版本。完成后在详情页第 5 步点 我已发布 确认。 详见飞书开发文档 应用发布与使用。
为了确保所有人可以使用应用,需将应用 可见范围 调整为全部员工,再进行应用发布。
飞书/Lark:应用发布与使用 界面截图

升级为自动管理

手动填写凭证接入的集成,详情页「在飞书完成配置」上方会出现「升级为自动管理,以后不用再去飞书后台改配置」的提示。用应用所有者或协作者的飞书账号扫码授权后,Flashduty 接管这个应用:上文 5 步不用再做,新功能需要的权限也会自动提交给飞书管理员审核。App Secret 和推送地址都不变,告警通知不中断。 Lark 国际版和私有化部署的集成不显示这个入口,继续按手动方式维护。

访问应用

应用发布后,即可通过 手机端 或 PC 端 访问应用。首次访问需要登录并关联飞书与 Flashduty 账号,后续可以免登录使用。 手机端和 PC 端的入口相同:飞书 → 工作台 → 搜索应用名称 → 打开应用。 飞书/Lark:PC 端 界面截图

配置作战室

完成先前步骤后,在 Flashduty On-call 集成配置页面的 增强功能 模块,勾选 开启作战室 即可启用该功能,无需额外配置。 同一时间只能有一个 IM 集成开启作战室,需先在其他集成中关闭,详见 作战室。

AI SRE 控制项

在 增强功能 中配置 AI SRE 开关,各开关含义见 IM 平台。允许在 IM 中使用 AI SRE 与 普通群聊中 AI-SRE 使用话题回复 默认开启;允许 AI 主动接话 默认关闭——开启后 AI 会读取群聊中未被 @ 的消息、判断值得回复时才回复,@ 仍然必回,且需要先按开通权限开通 im:message.group_msg 并订阅 im.message.receive_v1。

关联用户

在集成详情页的 关联用户 页签中,可按 全部 / 已关联 / 未关联 筛选成员,也可按名称或邮箱搜索。点击 一键关联,系统会用成员的手机号或邮箱匹配飞书账号并自动关联,效果等同于成员在飞书中登录 Flashduty。 成员完成关联后,才能收到飞书消息通知。关联失败时,请确认成员的手机号或邮箱与飞书账号一致。

自动关联

成员无需手动操作,系统会自动完成关联:保存集成后立即尝试一次,之后每小时再自动扫描一次,覆盖所有已启用的飞书集成。 自动关联使用成员在个人中心已验证的手机号或邮箱,分批(每批 50 个)调用飞书接口换取账号 ID。飞书对查不到的账号和不在应用 可见范围 内的用户都返回空 user_id,两者都按「未找到」处理。如果飞书应用缺少通讯录权限(错误码 99991672 / 99991679)或凭证被飞书拒绝,该集成的自动关联会暂停 24 小时,补齐权限并重新保存集成后即可恢复。 查询过、但没有查到对应飞书账号的成员,7 天内不会重复尝试;成员的联系方式发生变化时会重新尝试。一键关联 会忽略这个 7 天窗口,立即重新查询一次;如果提示 没有关联到新成员,说明本次查询没有产生新的绑定。

常见问题

前往 飞书 → 工作台 → 搜索应用名称 → 打开应用,完成一次登录以关联飞书与 Flashduty 账号,系统才能获取用户身份进行消息推送。如果成员在个人中心已经验证过手机号或邮箱,系统也可能已经自动完成关联,无需成员登录;可在集成详情页的 关联用户 页签确认当前关联状态。
  • 确保账户已经完成关联。您可以前往 飞书 → 工作台 → 搜索应用名称 → 打开应用,完成一次登录。如果已经登录过,请尝试点击右上角菜单,切换账户后重新登录以绑定账号
  • 确保已购买足够的 License。已使用 License 情况,可以在 控制台 → 费用中心 查看
  • 前往飞书,在指定群聊会话中添加已创建的 Flashduty 机器人
  • 回到分派策略配置页面,刷新后重新选择群聊列表
飞书/Lark:分派策略飞书群聊列表为空? 界面截图
调用量限制:频控限制:
超出 API 调用量限制后,飞书应用将无法正常推送消息,建议合理使用通知渠道。详见 飞书官方文档。