> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zoom

> 通过一键导入 Manifest 配置清单创建企业自建 Zoom 应用，在 Zoom 国际版或中国大陆专区内接收可交互告警卡片、拉起私密作战室并使用对话式 AI SRE。

> [!TIP]
>
> **版本要求**：所有版本均可创建 IM 应用用于 AI SRE 对话；将应用用于 On-call 分派通知，需有效的 On-call 专业版订阅。[了解更多](https://flashcat.cloud/flashduty/price/)

## 概览与架构对比

Flashduty 提供两种相互独立的 Zoom 接入方式：**Zoom Team Chat 应用**（通道标识 `zoom_app`，本页介绍）与传统的 **Zoom Incoming Webhook 机器人**（通道标识 `zoom`，详见 [通知渠道](https://docs.flashduty.com/zh/on-call/configuration/notifications.md)）。已有 Webhook 机器人配置不受影响，您可以按需并存或平滑迁移。

Zoom Team Chat 应用采用**企业自建 General App + Manifest 清单一键导入 + 自动代托管**模式，同时支持 **Zoom 国际版（`zoom.us`）** 与 **Zoom 中国大陆专区（`zoom.com.cn`）**，企业内部应用无需提交公共应用市场审核即可立即生效。

| 能力维度 | Zoom Team Chat 应用 (`zoom_app`) | Zoom Webhook 机器人 (`zoom`) |
| :- | :- | :- |
| **接入与运维方式** | 导入 `flashduty-zoom-manifest.json` 一键创建企业自建应用，首次 OAuth 后由 Flashduty 自动代托管配置与权限升级 | 单频道 Incoming Webhook 地址与 Verify Token，绑定创建者个人账号 |
| **多区域支持** | 原生支持国际版 `zoom.us`、中国大陆专区 `zoom.com.cn` 及自定义网关 | 依赖单频道 Webhook 地址 |
| **故障消息形态** | 可交互 Zoom App Card，支持就地认领、解决、暂缓、自定义操作并实时刷新状态 | 单向纯文本推送，不支持卡片按钮交互 |
| **个人 1:1 私聊通知** | 支持，成员可在个人通知偏好中勾选接收私聊卡片 | 不支持 |
| **值班交接班提醒** | 支持群聊频道通知与个人私聊提醒 | 仅支持群聊通知 |
| **成员身份识别** | 按企业邮箱自动匹配 Flashduty 成员，无需维护映射表 | 需手动收集 `zoom_jid` 并在配置中心维护映射表 |
| **自动故障作战室** | 支持一键或自动创建私密 Zoom 频道（Private Channel）并拉入响应人 | 不支持 |
| **对话式 AI SRE** | 支持频道 `@Flashduty`、机器人 1:1 私聊、`/fd` 斜杠命令、话题隔离与主动接话 | 不支持 |

> [!NOTE]
>
> 如果您仅需要单向群聊文本推送，仍可在分派策略中配置 [通知渠道](https://docs.flashduty.com/zh/on-call/configuration/notifications.md) 中的 Zoom 机器人；若需要双向故障卡片交互、个人私聊通知、自动私密作战室或 AI SRE 协同排障，请使用本页的 **Zoom Team Chat 应用**。

## 两步接入：Manifest 一键导入与自动代托管

新建 Zoom 集成时，系统会自动预生成专属 `integration_key` 并为您生成可直接导入的 Zoom App Manifest 文件，无需在 Zoom 开发者后台逐项填写回调地址、斜杠命令或事件订阅。

**1. 创建应用**

访问 Flashduty 控制台 **集成中心 → 即时消息 → Zoom**，点击 **添加**：

1. 点击 **下载配置清单**（或 **复制 JSON**）。该配置清单对所有 Zoom 区域通用；如果您的企业使用中国大陆版 Zoom，可在右上角切换至 **中国大陆 (`zoom.com.cn`)**（专用网关可点击 **自定义域名**）。
2. 点击 **打开 Zoom 后台**，依次选择 **Develop → Build App → General App**，选择 **Manifest file** 上传 `flashduty-zoom-manifest.json` 创建企业内部应用。

**2. 填写凭证并保存授权**

按 Zoom 后台左侧菜单顺序复制以下信息，填入 Flashduty 表单的 **步骤 2**（企业内部自建应用请统一复制默认 **Development** 页签下的凭证，无需切换至 Production 或提交公开上架）：

* **Client ID** 与 **Client Secret**：位于 **Basic Information** 页（Development 环境）。
* **App ID**：位于浏览器地址栏 `/develop/applications/{id}`（支持直接粘贴完整链接）。
* **Secret Token**：位于 **Features → Access** 页。
* **Bot JID**：位于 **Features → Surface → Team Chat**，形如 `v1...@xmpp.zoom.us`（与所选 Development 环境配套）。

按需配置下方的 **开启作战室** 或 **允许 AI 主动接话** 等增强功能，点击页面底部 **保存**：

1. Flashduty 先加密保存集成凭证，使专属回调地址立即可响应 Zoom 的 URL 校验请求。
2. 浏览器自动跳转至 Zoom OAuth 授权页，使用管理员或应用所有者账号点击 **Allow** 确认授权，回跳后集成即刻生效。

### 自动代托管与配置自愈

完成首次 OAuth 授权后，集成详情页的 **Zoom 应用与自动代托管** 卡片会通过 Zoom App Manifest 接口持续核对应用状态：

* **配置漂移检测与一键自愈**：若有人在 Zoom 后台误删了 `/fd` 斜杠命令、改动了事件回调地址或遗漏了必需权限，详情页会列出具体偏差项并提供 **一键同步修复配置** 按钮。点击后 Flashduty 会自动拉取远端 Manifest、保留您自定义的应用名称与图标，并将回调、命令和权限恢复至预期状态。
* **功能升级零手工改表**：后续开启需要额外权限或新事件订阅的功能（如主动接话）时，无需再次打开 Zoom 开发者后台改配置，直接在 Flashduty 详情页或编辑页一键写入即可。

### 成员关联说明

Zoom Team Chat 集成不设手动 **关联用户** 页签，也无需维护 `zoom_jid` 映射表。Flashduty 通过企业**邮箱**（忽略大小写）自动关联成员：

* 发送个人 1:1 私聊告警或邀请成员加入作战室时，系统按 Flashduty 成员邮箱查询同组织下的 Zoom 用户。
* 成员在 Zoom 中点击告警卡片按钮或向 AI SRE 提问时，系统读取操作者的 Zoom 邮箱并与当前账户成员比对。请确保成员的 Zoom 账号邮箱与 Flashduty 登录邮箱一致；若未匹配到成员，系统会在 Zoom 中提示邮箱未关联。

## 权限分级说明

Flashduty 遵循最小权限原则，将 Zoom OAuth 权限拆分为**默认必需权限**与**主动接话可选权限**两档。

### 默认必需权限（Required Scopes）

默认生成的 `flashduty-zoom-manifest.json` 包含以下 13 项权限，覆盖卡片通知、私密作战室、AI SRE 对话及应用生命周期自动代托管：

| 官方 scope 名称 | 用途 |
| :- | :- |
| `imchat:bot` | 注册 Team Chat 机器人收发能力，接收 `@` 提及与专属 `/fd_<后缀>` 斜杠命令 |
| `app:channel_content:write:admin` | 通过 Zoom Team Chat 应用卡片通道向频道发送富文本与交互式卡片内容 |
| `team_chat:write:user_message:admin` | 向频道与个人私聊发送故障卡片、值班提醒、作战室通知和 AI SRE 回复 |
| `team_chat:update:user_message:admin` | 就地更新故障卡片处理状态，以及流式刷新 AI SRE 排查进展 |
| `team_chat:read:list_user_channels:admin` | 读取授权用户可见的 Zoom 频道列表（含已加入的私有频道），供分派策略和值班表下拉选择 |
| `team_chat:read:list_channels:admin` | 读取账户级公开频道目录，补全工作区内的公共频道下拉列表 |
| `team_chat:write:user_channel:admin` | 为故障自动创建专属私密作战室频道 |
| `team_chat:write:members:admin` | 按成员邮箱批量邀请故障响应人员加入作战室频道 |
| `team_chat:read:file:admin` | 下载会话中附带的报错截图与日志文件（单文件上限 25 MB，仅允许受信任 Zoom 域名）供 AI SRE 分析 |
| `user:read:user:admin` | 读取单个 Zoom 用户基础信息与邮箱，用于自动成员匹配 |
| `user:read:list_users:admin` | 列出组织内 Zoom 用户并按邮箱批量匹配 Flashduty 成员 |
| `marketplace:read:app:admin` | 读取当前自建应用的 Manifest 配置，用于检测回调、命令或权限是否发生偏差 |
| `marketplace:write:app:admin` | 自动同步修复应用配置偏差，并在开启新功能时一键向自建应用写入所需权限与事件订阅 |

### 主动接话可选权限（Optional Scopes）

以下两项频道消息读取权限属于敏感权限，**默认不包含在初始启用权限中**，仅在您需要开启 **允许 AI 主动接话** 时按需注入并授权：

| 官方 scope 名称 | 用途 |
| :- | :- |
| `team_chat:read:user_message:admin` | 接收频道内未 `@` 机器人的普通消息事件（`chat_message.sent`、`chat_message.replied`、`team_chat.channel_message_posted`），用于上下文缓冲与主动接话判断 |
| `team_chat:read:list_user_messages:admin` | 读取频道与话题历史消息，用于补充 AI SRE 排障上下文及生成故障复盘摘要 |

> [!NOTE]
>
> **零手工配置的按需授权体验**：
>
> * **新建时保持关闭（默认）**：OAuth 仅申请默认必需权限，不会请求群聊普通消息读取权限。
> * **新建时直接开启**：无论您在下载配置清单之前还是之后打开 **允许 AI 主动接话**，点击 **保存** 时都会在同一次 Zoom 授权中申请该权限，并在授权回调时自动把 `chat_message.sent`、`chat_message.replied` 事件同步写入您的自建 Zoom 应用，无需重传 JSON。
> * **后续编辑时开启**：日后在编辑页打开 **允许 AI 主动接话** 并点击 **保存**，Flashduty 会自动为您的应用补齐事件配置并跳转至 Zoom 确认一次授权，确认后立即生效。

## 告警通知与自动私密作战室

### 频道可交互告警卡片

前往 **协作空间 → 分派策略**，在群聊通知方式中选择 **Zoom 应用**，即可直接下拉选择整个 Zoom 工作区内的**全部公共频道**，以及**授权管理员或您本人已加入的私有频道**（无需提前在频道中手动拉入机器人）。选定集成实例与目标频道后保存即可。

故障触发后，Flashduty 会向频道推送交互式 App Card：

* **快捷响应操作**：支持直接在卡片上执行 **认领**、**解决**、**暂缓**、**拉起作战室** 及预设的**自定义操作**，操作完成后卡片状态就地刷新。
* **自定义通知模板**：支持在 [通知模板](https://docs.flashduty.com/zh/on-call/configuration/templates.md) 中定制 `Zoom` 应用渠道模板（Go `text/template` 语法，单条卡片上限 15,000 字节）。

### 个人私聊通知与值班提醒

* **个人 1:1 故障通知**：成员进入 **个人设置 → 通知偏好**，在故障通知渠道中勾选已启用的 Zoom 应用，即可通过 Zoom 1:1 私聊接收分派给自己的交互式故障卡片。
* **值班交接班提醒**：在 [值班管理](https://docs.flashduty.com/zh/on-call/configuration/schedule.md) 的值班通知设置中，支持选择 **Zoom 应用** 向指定频道广播排班动态，同时支持向当班成员发送个人私聊提醒。

### 自动私密作战室与 AI 根因分析

在 Zoom 集成的 **增强功能** 区域，**开启作战室**（`war_room_enabled`）默认关闭，需按需手动开启（同一账户同一时间仅支持一个 IM 集成开启作战室）；**自动发起 AI 故障分析** 为独立开关（默认开启，在作战室功能已开启且命中账户内的作战室创建触发规则时生效）：

* **私密频道隔离**：从故障详情页、告警卡片或分派策略拉起作战室时，Flashduty 默认创建 **私密 Zoom 频道（Private Channel）**，按邮箱自动分批拉入故障处理人，并发送置顶故障摘要卡片。
* **自动根因分析**：当 **开启作战室** 与 **自动发起 AI 故障分析** 均开启且命中账户内的作战室创建触发规则时，AI SRE 会在作战室建群后立即结合故障详情、时间线与近期变更输出首轮根因诊断。更多规则说明见 [作战室](https://docs.flashduty.com/zh/on-call/advanced/war-room.md)。

## 对话式 AI SRE

在集成中开启 **允许在 IM 中使用 AI SRE**（默认开启）后，团队成员可在 Zoom Team Chat 内直接协同排障。通用会话机制见 [IM 平台](https://docs.flashduty.com/zh/ai-sre/im.md)。

### 交互入口与流式回执

* **频道 `@Flashduty` 提问**：在已接入的频道中提及 `@Flashduty` 并输入问题；若需带上频道内更早的报错文本或截图，可回复该消息后再 `@Flashduty`。
* **机器人 1:1 私聊**：在 Zoom Team Chat 中直接打开与自建 Flashduty 应用的私聊窗口提问，适合个人独立排查。
* **流式卡片更新与宽表展示**：由于 Zoom Team Chat 机器人接口不提供消息表情回执，AI SRE 收到请求后会立即发送一条「思考中」占位卡片，并按节流间隔就地更新分析进展与最终结论。当分析结果包含超过 4 列的宽表格或长篇报告时，AI SRE 提示词会引导模型在卡片中给出精简摘要并通过产物发布功能附带可点击的完整查看链接；若回复中直接包含宽表格，卡片渲染器会自动降级为对齐的等宽代码块并提取其中的链接展示。

### `/fd_<后缀>` 斜杠命令

导入配置清单时，系统会基于集成的 `integration_key` 自动派生一个建议斜杠命令前缀（格式为 `/fd_<6位字符>`，形如 `/fd_1a2b3c`；若与 Zoom 中已有命令冲突，可在 Zoom 后台按需修改），在 Zoom 频道或机器人私聊中可使用该命令向 AI SRE 提问或管理会话：

| 命令 | 说明 |
| :- | :- |
| `/fd_<后缀> <问题>` | 直接向 AI SRE 发起自由提问或在当前会话中继续追问（非保留子命令的输入均会路由给 AI SRE 处理） |
| `/fd_<后缀> new [消息]` | 重置当前会话上下文并开启全新对话；若附带消息则直接以该消息开始排查 |
| `/fd_<后缀> env [环境名]` | 查看可用运行环境、切换至指定 Runner 或沙箱环境，或执行 `/fd_<后缀> env clear` 恢复默认环境 |
| `/fd_<后缀> scope [团队名]` | 查看当前会话绑定的团队与协作空间范围、切换目标团队，或执行 `/fd_<后缀> scope clear` 恢复默认范围 |
| `/fd_<后缀> help` | 查看支持的子命令与用法提示 |

此外，在开启主动接话的群聊中，您还可以发送 `/ambient on`、`/ambient off`、`/ambient inherit` 或 `/ambient status` 单独控制当前频道的主动接话行为。

### 话题回复隔离与主动接话

* **普通群聊中 AI-SRE 使用话题回复**（默认开启）：开启后，AI SRE 发送回复时会同时设置出站线程字段 `reply_to` 与 `reply_main_message_id` 将消息挂入原话题（Thread），并依据入站回调中的 `parent_msg_id` / `reply_main_message_id` 识别所属话题，为每个话题绑定独立的排查 Session（`group_thread`），互不串扰；关闭后则在频道主消息流中回复并共用频道级 Session（`group_chat`）。作战室频道始终直接在群内回复。
* **允许 AI 主动接话**（默认关闭）：仅在开启该开关并完成[主动接话可选权限](#ambient-scopes)授权后，系统才会对频道内未 `@` 机器人的普通消息进行上下文缓冲（维护最近 30 条、24 小时内有效），并在判定需要介入排障时主动回复；关闭该开关后，系统不会缓冲普通频道消息，也不会主动插话。

## 私有化部署说明

私有化部署版 Flashduty 与 SaaS 版共享完全一致的 **Manifest 一键导入 + 自动代托管** 体验：

1. 确保您的 Flashduty 控制台域名（如 `https://console.example.com`）与事件网关域名（如 `https://api.example.com`）对 Zoom 服务器可达（满足回调签名校验与事件推送），并在私有化环境中确保 Zoom 插件配置（`t_data_source_plugin.settings`）中的 `event_url` 或部署级事件网关配置指向您的私有事件网关（避免沿用公有云默认地址）。
2. 在控制台新建 Zoom 集成并下载 `flashduty-zoom-manifest.json` 时，事件回调地址（`.../event/push/zoom_app/data?integration_key=<key>`）按优先级依次取自 Zoom 插件的 `event_url` 配置与部署级事件网关配置（缺失时回退至默认模板）；OAuth 重定向地址（`https://console.example.com/settings/source/im/add/zoom_app`）则按集成/控制台来源、`deploy.zoomRedirectURI` 与部署域名顺序解析。导入清单前请核对两个地址均已指向您的私有化环境。

如果您希望在单租户私有化环境中配置全局兜底凭证（当数据源未单独填写凭证时自动回退使用），可在 `fc-datasource` 与 `fc-event` 的 `etc/*.yaml` 中按需配置以下可选字段（或注入同名环境变量 `ZOOM_CLIENT_ID`、`ZOOM_CLIENT_SECRET`、`ZOOM_SECRET_TOKEN`、`ZOOM_BOT_JID`、`ZOOM_REDIRECT_URI`）：

```yaml theme={null}
deploy:
  zoomClientID: "<YOUR_ZOOM_CLIENT_ID>"
  zoomClientSecret: "<YOUR_ZOOM_CLIENT_SECRET>"
  zoomSecretToken: "<YOUR_ZOOM_SECRET_TOKEN>"
  zoomBotJID: "<YOUR_ZOOM_BOT_JID>"
  zoomRedirectURI: "https://console.example.com/settings/source/im/add/zoom_app"
```

## 常见问题

> [accordion] Zoom 国际版（zoom.us）与中国大陆专区（zoom.com.cn）应该如何选择？
>
> 请根据您团队登录 Zoom 客户端与开发者后台的实际域名选择。若您的企业账号托管在 `zoom.com.cn`，请在步骤 1 选择 **Zoom 中国大陆专区 (`zoom.com.cn`)**，Flashduty 会自动将 API 地址切换至 `https://api.zoom.com.cn`、OAuth 地址切换至 `https://zoom.com.cn`，并引导您在 `marketplace.zoom.com.cn` 导入配置清单。

> [accordion] 分派策略或值班表的频道下拉列表中找不到目标 Zoom 频道？
>
> * 确认 Zoom 集成已完成 OAuth 授权且状态为启用
> * 公共频道默认全量可见；若目标为私密频道（Private Channel），只需确保**当前登录配置页的您本人**（需 Zoom 邮箱与 Flashduty 邮箱一致）或**完成 OAuth 授权的管理员**已加入该私密频道
> * 返回 Flashduty 分派策略或值班表配置页，点击频道选择框右侧的刷新按钮重新拉取频道列表（服务端频道列表默认缓存 5 分钟，手动刷新会立即更新）

> [accordion] 点击 Zoom 故障卡片按钮时提示未匹配到成员？
>
> Zoom Team Chat 集成通过成员邮箱识别操作人。请核对您在 Zoom 客户端登录账号的邮箱是否与 Flashduty **成员管理** 中的邮箱一致（大小写不敏感）；修改一致后即可直接操作卡片，无需手动绑定。

> [accordion] 开启「允许 AI 主动接话」为什么需要再次确认 Zoom 授权？
>
> 默认导入的 Manifest 仅申请基础必需权限，不包含读取频道普通消息的敏感权限（`team_chat:read:user_message:admin` 与 `team_chat:read:list_user_messages:admin`）。当您打开该开关并点击 **保存** 时，Flashduty 会自动将所需权限与消息事件写入您的自建 Zoom 应用并引导您完成一次增量授权，无需手动修改配置清单。

> [accordion] 开启作战室时有哪些注意事项？
>
> * 同一账户下同一时间只能有一个 IM 集成开启作战室；若其他 IM 集成已启用作战室，请先在对应集成中关闭，详见 [作战室](https://docs.flashduty.com/zh/on-call/advanced/war-room.md)
> * 若检测到应用配置发生偏差或缺少必需权限，可在集成详情页点击 **一键同步修复配置** 并完成重新授权


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.