build-zoom-rest-api-app

/build-zoom-rest-api-app

用于确定性服务端 Zoom 自动化与资源管理的背景参考。请先使用 plan-zoom-product、plan-zoom-integration 或 debug-zoom，再转到此处查阅端点级别的详细信息。

Zoom REST API

构建 Zoom REST API 服务端集成的专业指南。该 API 提供 600 多个端点，用于以编程方式管理会议、用户、网络研讨会、录制、报告以及 Zoom 平台的所有资源。

官方文档：https://developers.zoom.us/api-hub/ API Hub 参考：https://developers.zoom.us/api-hub/meetings/ OpenAPI 清单：https://developers.zoom.us/api-hub/<domain>/methods/endpoints.json

快速链接

初次使用 Zoom REST API？请按以下路径操作：

1. API 架构：基础 URL、区域 URL、me 关键字、ID 与 UUID、时间格式
2. 身份验证流程：OAuth 设置（S2S、User、PKCE、Device Code）
3. 会议 URL 与 Meeting SDK：请勿将 join_url 与 Meeting SDK 混用
4. 会议生命周期：创建 → 更新 → 开始 → 结束 → 删除，并结合 Webhook
5. 速率限制策略：套餐层级、按用户限制、重试模式

参考资料：

• 会议：会议的增删改查、类型、设置
• 用户：用户开通与管理
• 录制：云端录制的访问与下载
• AI 服务：Scribe 端点清单及当前 AI 服务路径范围
• GraphQL 查询：替代查询 API（测试版）
• 集成索引：参见本文件下方的相关章节

references/ 下的大多数领域文件均与官方 API Hub endpoints.json 清单保持一致。请将这些文件视为方法与路径查找的本地权威来源。

遇到问题？

• 从预检查开始 → 5 分钟操作手册
• 401 Unauthorized → 身份验证流程（检查令牌有效期、权限范围）
• 429 Too Many Requests → 速率限制策略
• 错误代码 → 常见错误
• 分页混淆 → 常见问题
• Webhook 未送达 → Webhook 服务器
• 论坛高频问题 → 论坛热门问题
• 令牌或权限范围失败 → 令牌与权限范围排查手册

正在构建事件驱动型集成？

• Webhook 服务器：基于 Express.js 的服务器，含 CRC 验证
• 录制流水线：通过 Webhook 事件自动下载

快速开始

获取访问令牌（服务器到服务器 OAuth）

curl -X POST "https://zoom.us/oauth/token" \
  -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=account_credentials&account_id=ACCOUNT_ID"

响应：

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "meeting:read meeting:write user:read"
}

创建会议

curl -X POST "https://api.zoom.us/v2/users/HOST_USER_ID/meetings" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Team Standup",
    "type": 2,
    "start_time": "2025-03-15T10:00:00Z",
    "duration": 30,
    "settings": {
      "join_before_host": false,
      "waiting_room": true
    }
  }'

对于 S2S OAuth，请在路径中使用明确的主持人用户 ID 或邮箱，不要使用 me。

使用分页列出用户

curl "https://api.zoom.us/v2/users?page_size=300&status=active" \
  -H "Authorization: Bearer ACCESS_TOKEN"

基础 URL

https://api.zoom.us/v2

区域基础 URL

OAuth 令牌响应中的 api_url 字段表示用户所在的区域。为满足数据驻留合规要求，请使用区域 URL：

区域	URL
全球（默认）	https://api.zoom.us/v2
澳大利亚	https://api-au.zoom.us/v2
加拿大	https://api-ca.zoom.us/v2
欧盟	https://api-eu.zoom.us/v2
印度	https://api-in.zoom.us/v2
沙特阿拉伯	https://api-sa.zoom.us/v2
新加坡	https://api-sg.zoom.us/v2
英国	https://api-uk.zoom.us/v2
美国	https://api-us.zoom.us/v2

注意： 无论 api_url 的值是什么，您始终可以使用全球 URL https://api.zoom.us。

主要功能

功能	描述
会议管理	创建、读取、更新、删除会议，完整控制日程安排
用户配置	自动化用户生命周期管理（创建、更新、停用、删除）
网络研讨会操作	网络研讨会的增删改查、注册人管理、小组成员控制
云端录制	列出、下载、删除录制文件，支持按文件类型筛选
报告与分析	使用情况报告、参会者数据、每日统计
团队聊天	频道管理、消息收发、聊天机器人集成
Zoom Phone	通话管理、语音信箱、呼叫路由
Zoom Rooms	会议室管理、设备控制、日程安排
Webhooks	针对 100 多种事件类型的实时事件通知
WebSockets	无需公共端点的持久化事件流
GraphQL（测试版）	通过 v3/graphql 单一端点进行灵活查询
AI Companion	会议摘要、逐字稿、AI 生成内容
AI 服务 / Scribe	通过 Build 平台 JWT 认证端点进行文件和压缩包转写

前提条件

• Zoom 账户（免费版可使用 API，但速率限制较低）
• 已在 Zoom App Marketplace 注册应用
• OAuth 凭据（Server-to-Server OAuth 或 User OAuth）
• 目标端点所需的相应权限范围（scopes）

需要认证方面的帮助？ 请参阅 zoom-oauth 技能，了解完整的 OAuth 流程实现。

关键注意事项与最佳实践

⚠️ JWT 应用类型已弃用

JWT 应用类型已弃用，请迁移至 Server-to-Server OAuth。这不会影响 Video SDK 中使用的 JWT 令牌签名，仅影响 Marketplace 中用于 REST API 访问的"JWT"应用类型。

// OLD (JWT app type - DEPRECATED)
const token = jwt.sign({ iss: apiKey, exp: expiry }, apiSecret);

// NEW (Server-to-Server OAuth)
const token = await getServerToServerToken(accountId, clientId, clientSecret);

⚠️ me 关键字使用规则

• 用户级 OAuth 应用：必须使用 me 代替 userId（否则会返回无效令牌错误）
• Server-to-Server OAuth 应用：不得使用 me，需提供实际的 userId 或邮箱
• 账户级 OAuth 应用：可以使用 me 或 userId

⚠️ 会议 ID 与 UUID：双重编码

以 / 开头或包含 // 的 UUID 必须进行双重 URL 编码：

// UUID: /abc==
// Single encode: %2Fabc%3D%3D
// Double encode: %252Fabc%253D%253D  ← USE THIS

const uuid = '/abc==';
const encoded = encodeURIComponent(encodeURIComponent(uuid));
const url = `https://api.zoom.us/v2/meetings/${encoded}`;

⚠️ 时间格式

• yyyy-MM-ddTHH:mm:ssZ：UTC 时间（注意结尾的 Z）
• yyyy-MM-ddTHH:mm:ss：本地时间（无 Z，使用 timezone 字段）
• 部分报告 API 仅接受 UTC 时间，请查阅各端点的 API 参考文档。

⚠️ 速率限制基于账户，而非应用

同一 Zoom 账户下的所有应用共享速率限制，一个高负载应用可能影响其他应用。请主动监控 X-RateLimit-Remaining 响应头。

⚠️ 每用户每日限制

会议/网络研讨会的创建和更新操作，每个用户每天最多 100 次（于 UTC 时间 00:00 重置）。进行批量操作时，请将操作分散到不同的主持人用户上。

⚠️ 下载链接需要认证且会重定向

录制文件的 download_url 需要 Bearer 令牌认证，并且可能发生重定向。请务必跟随重定向：

curl -L -H "Authorization: Bearer ACCESS_TOKEN" "https://zoom.us/rec/download/..."

使用 Webhooks 代替轮询

// DON'T: Poll every minute (wastes API quota)
setInterval(() => getMeetings(), 60000);

// DO: Receive webhook events in real-time
app.post('/webhook', (req, res) => {
  if (req.body.event === 'meeting.started') {
    handleMeetingStarted(req.body.payload);
  }
  res.status(200).send();
});

Webhook 设置详情： 请参阅 zoom-webhooks 技能，了解完整的 Webhook 实现方法。

完整文档库

本技能包含按类别组织的完整指南：

核心概念

• API 架构 - REST 设计、基础 URL、区域路由、me 关键字、ID 与 UUID、时间格式
• 认证流程 - 所有 OAuth 流程（S2S、User、PKCE、Device Code）
• 速率限制策略 - 按套餐划分的限制、重试模式、请求排队

完整示例

• 会议生命周期 - 包含 Webhook 事件的完整 创建 → 更新 → 开始 → 结束 → 删除 流程
• 用户管理 - 用户的增删改查、分页列表和批量操作
• 录制处理流水线 - 通过 Webhook 和 API 下载录制文件
• Webhook 服务 - 基于 Express.js 的服务，包含 CRC 验证和签名校验
• GraphQL 查询 - GraphQL 查询、变更和游标分页

故障排查

• 常见错误 - HTTP 状态码、Zoom 错误码和错误响应格式
• 常见问题 - 速率限制、令牌刷新、分页陷阱和注意事项

参考文档（共 39 个文件，覆盖所有 Zoom API 领域）

核心 API

• references/meetings.md - 会议的增删改查、类型和设置
• references/users.md - 用户配置、类型和权限范围
• references/webinars.md - 网络研讨会管理和报名者
• references/recordings.md - 云端录制访问
• references/reports.md - 使用情况报告和分析
• references/accounts.md - 账户管理

通信

• references/team-chat.md - Team Chat 消息
• references/chatbot.md - 交互式聊天机器人
• references/phone.md - Zoom Phone
• references/mail.md - Zoom Mail
• references/calendar.md - Zoom Calendar

基础设施

• references/rooms.md - Zoom Rooms
• references/scim2.md - SCIM 2.0 配置 API
• references/rate-limits.md - 速率限制详情
• references/qss.md - 服务质量订阅（Quality of Service Subscription）

高级

• references/graphql.md - GraphQL API（测试版）
• references/ai-companion.md - AI 功能
• references/authentication.md - 认证参考
• references/openapi.md - OpenAPI 规范、Postman 和代码生成

其他 API 领域

• references/events.md - 活动及活动平台 API
• references/scheduler.md - Zoom Scheduler API
• references/tasks.md - Tasks API
• references/whiteboard.md - Whiteboard API
• references/video-management.md - 视频管理 API
• references/video-sdk-api.md - Video SDK REST API
• references/marketplace-apps.md - Marketplace 应用管理
• references/commerce.md - 商务及计费 API
• references/contact-center.md - Contact Center API
• references/quality-management.md - 质量管理 API
• references/workforce-management.md - 劳动力管理 API
• references/healthcare.md - 医疗保健 API
• references/auto-dialer.md - 自动拨号 API
• references/number-management.md - 号码管理 API
• references/revenue-accelerator.md - Revenue Accelerator API
• references/virtual-agent.md - Virtual Agent API
• references/cobrowse-sdk-api.md - Cobrowse SDK API
• references/crc.md - Cloud Room Connector API
• references/clips.md - Clips API
• references/zoom-docs.md - Zoom 文档及源码参考

示例仓库

官方（由 Zoom 提供）

类型	仓库
OAuth 示例	oauth-sample-app
S2S OAuth 入门	server-to-server-oauth-starter-api
用户 OAuth	user-level-oauth-starter
S2S Token	server-to-server-oauth-token
Rivet 库	rivet-javascript
WebSocket 示例	websocket-js-sample
Webhook 示例	webhook-sample-node.js
Python S2S	server-to-server-python-sample

资源

• API 参考：https://developers.zoom.us/api-hub/
• GraphQL Playground：https://nws.zoom.us/graphql/playground
• Postman Collection：https://marketplace.zoom.us/docs/api-reference/postman
• 开发者论坛：https://devforum.zoom.us/
• 更新日志：https://developers.zoom.us/changelog/
• 状态页面：https://status.zoom.us/

---

需要帮助？ 请从下方的综合索引部分开始浏览完整导航。

---

综合索引

本节内容迁移自 SKILL.md。

快速入门路径

如果你是 Zoom REST API 的新手，请按以下顺序操作：

1. 先运行预检 → RUNBOOK.md

2. 了解 API 设计 → concepts/api-architecture.md

   • 基础 URL、区域端点、me 关键字规则
   • 会议 ID 与 UUID、双重编码、时间格式

3. 设置身份验证 → concepts/authentication-flows.md

   • 服务端到服务端 OAuth（后端自动化）
   • 使用 PKCE 的用户 OAuth（面向用户的应用）
   • 交叉参考：zoom-oauth

4. 创建你的第一个会议 → examples/meeting-lifecycle.md

   • 包含 curl 和 Node.js 示例的完整 CRUD
   • Webhook 事件集成

5. 处理速率限制 → concepts/rate-limiting-strategy.md

   • 基于套餐的限制、重试模式、请求排队

6. 设置 Webhook → examples/webhook-server.md

   • CRC 验证、签名验证、事件处理

7. 排查问题 → troubleshooting/common-issues.md

   • 令牌刷新、分页陷阱、常见易错点

---

文档结构

rest-api/
├── SKILL.md                              # Main skill overview + quick start
├── SKILL.md                              # This file - navigation guide
│
├── concepts/                             # Core architectural concepts
│   ├── api-architecture.md              # REST design, URLs, IDs, time formats
│   ├── authentication-flows.md          # OAuth flows (S2S, User, PKCE, Device)
│   └── rate-limiting-strategy.md        # Limits by plan, retry, queuing
│
├── examples/                             # Complete working code
│   ├── meeting-lifecycle.md             # Create→Update→Start→End→Delete
│   ├── user-management.md              # CRUD users, pagination, bulk ops
│   ├── recording-pipeline.md           # Download recordings via webhooks
│   ├── webhook-server.md               # Express.js CRC + signature verification
│   └── graphql-queries.md              # GraphQL queries, mutations, pagination
│
├── troubleshooting/                      # Problem solving
│   ├── common-errors.md                # HTTP codes, Zoom error codes table
│   └── common-issues.md               # Rate limits, tokens, pagination pitfalls
│
└── references/                           # 39 domain-specific reference files
    ├── authentication.md                # Auth methods reference
    ├── meetings.md                      # Meeting endpoints
    ├── users.md                         # User management endpoints
    ├── webinars.md                      # Webinar endpoints
    ├── recordings.md                    # Cloud recording endpoints
    ├── reports.md                       # Reports & analytics
    ├── accounts.md                      # Account management
    ├── rate-limits.md                   # Rate limit details
    ├── graphql.md                       # GraphQL API (beta)
    ├── zoom-team-chat.md                     # Team Chat messaging
    ├── chatbot.md                       # Chatbot integration
    ├── phone.md                         # Zoom Phone
    ├── rooms.md                         # Zoom Rooms
    ├── calendar.md                      # Zoom Calendar
    ├── mail.md                          # Zoom Mail
    ├── ai-companion.md                  # AI features
    ├── openapi.md                       # OpenAPI specs
    ├── qss.md                           # Quality of Service
    ├── contact-center.md                # Contact Center
    ├── events.md                        # Zoom Events
    ├── whiteboard.md                    # Whiteboard
    ├── clips.md                         # Zoom Clips
    ├── scheduler.md                     # Scheduler
    ├── scim2.md                         # SCIM 2.0
    ├── marketplace-apps.md              # App management
    ├── zoom-video-sdk-api.md                 # Video SDK REST
    └── ... (39 total files)

---

按使用场景查找

我想创建和管理会议

1. API 架构 - 基础 URL、时间格式
2. 会议生命周期 - 完整 CRUD + Webhook 事件
3. 会议参考 - 所有端点、类型、设置

我想以编程方式管理用户

1. 用户管理 - CRUD、分页、批量操作
2. 用户参考 - 端点、用户类型、权限范围

我想自动下载录制文件

1. 录制流水线 - 由 Webhook 触发的下载
2. 录制参考 - 文件类型、下载身份验证

我想接收实时事件

1. Webhook 服务 - CRC 验证、签名检查
2. 交叉参考：zoom-webhooks，查看完整的 Webhook 文档
3. 交叉参考：zoom-websockets，查看 WebSocket 事件

我想使用 GraphQL 替代 REST

1. GraphQL 查询 - 查询、变更、分页
2. GraphQL 参考 - 可用实体、权限范围、速率限制

我想设置身份验证

1. 身份验证流程 - 所有 OAuth 方法
2. 交叉参考：zoom-oauth，查看完整的 OAuth 实现

我遇到了速率限制

1. 速率限制策略 - 按套餐划分的限制、应对策略
2. 速率限制参考 - 详细表格
3. 常见问题 - 实用解决方案

我遇到了错误

1. 常见错误 - 错误码表
2. 常见问题 - 诊断流程

我想开发网络研讨会

1. 网络研讨会参考 - 端点、类型、注册者
2. 会议生命周期 - 类似的模式同样适用

我想集成 Zoom Phone

1. Phone 参考 - Phone API 端点
2. 速率限制策略 - Phone 的独立速率限制

---

最重要的文档

1. API 架构（基础）

concepts/api-architecture.md

在进行任何 API 调用之前必须掌握的知识：

• 基础 URL 与区域端点
• me 关键字规则（因应用类型而异！）
• 会议 ID 与 UUID 的双重编码
• ISO 8601 时间格式（UTC 与本地时间）
• 下载 URL 的身份验证

2. 限流策略（生产环境最常见的问题）

concepts/rate-limiting-strategy.md

限流按账户计算，并在所有应用之间共享：

• 免费版：轻量级 4/秒，中等 2/秒，重量级 1/秒
• Pro 版：轻量级 30/秒，中等 20/秒，重量级 10/秒
• Business+ 版：轻量级 80/秒，中等 60/秒，重量级 40/秒
• 单用户：每天 100 次会议创建/更新

3. 会议生命周期（最常见的任务）

examples/meeting-lifecycle.md

包含 Webhook 集成的完整 CRUD，是大多数开发者首先需要的模式。

---

关键经验

重要发现：

1. JWT 应用类型已弃用，请改用 Server-to-Server OAuth

   • 被弃用的是 Marketplace 上的 JWT 应用类型，而不是 JWT 令牌签名
   • 参见：身份验证流程

2. me 关键字的行为因应用类型而异

   • User OAuth：必须使用 me
   • S2S OAuth：禁止使用 me
   • 参见：API 架构

3. 限流规则较为复杂（不要假设只有一条全局规则）

   • 限制可能因端点而异，并可能在账户、应用或用户层面执行
   • 应将配额视为可能在整个账户内共享，并实现退避机制
   • 监控限流响应头（例如 X-RateLimit-Remaining）
   • 参见：限流策略

4. 每个用户每天最多创建 100 次会议

   • 这是硬性的单用户限制，与速率限制无关
   • 批量操作时，应将请求分散到多个主持人用户上
   • 参见：限流策略

5. 某些 UUID 需要进行双重编码

   • 以 / 开头或包含 // 的 UUID 必须进行双重编码
   • 参见：API 架构

6. 分页使用 next_page_token，而不是 page_number

   • page_number 是旧版参数，正在逐步淘汰
   • 推荐使用 next_page_token
   • 参见：常见问题

7. GraphQL 位于 /v3/graphql，而不是 /v2/

   • 单一端点，基于游标的分页
   • 限流按字段计算（每个字段相当于一个 REST 端点）
   • 参见：GraphQL 查询

---

快速参考

"401 Unauthorized"

→ 身份验证流程：令牌已过期或权限范围不正确

"429 Too Many Requests"

→ 限流策略：查看响应头中的重置时间

使用 userId 时出现 "Invalid token"

→ API 架构：User OAuth 应用必须使用 me

"如何对结果进行分页？"

→ 常见问题：使用 next_page_token

"Webhook 没有收到推送"

→ Webhook 服务：需要完成 CRC 验证

"录制文件下载失败"

→ 录制处理流程：使用 Bearer 认证并跟随重定向

"如何创建会议？"

→ 会议生命周期：完整的可运行示例

---

相关 Skills

Skill	使用场景
zoom-oauth	实现 OAuth 流程、令牌管理
zoom-webhooks	深入的 Webhook 实现、事件目录
zoom-websockets	WebSocket 事件流
zoom-general	跨产品模式、社区仓库

---

基于 Zoom REST API v2（当前版本）和 GraphQL v3（测试版）

环境变量

• 参见 references/environment-variables.md，了解标准化的 .env 键名以及每个值的获取位置。