zoom-rest-api

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. 速率限制策略 - 计划层级、用户级限制、重试模式

参考：

• 会议 - 会议 CRUD、类型、设置
• 用户 - 用户配置与管理
• 录制内容 - 云录制访问与下载
• AI 服务 - Scribe、Summarizer 和 Translator 端点清单，以及当前 AI Services 路径概览
• Marketplace 应用 - 应用创建、清单验证、原生应用类型和响应差异
• Marketplace 模板 - 场景清单、原生创建请求以及仅合并的功能片段
• Connect、Actions 和 Triggers - 外部 REST/MCP 连接器和由清单管理的工作流功能
• GraphQL 查询 - 替代查询 API（测试版）
• 集成索引 - 请参阅本文件下方的章节

references/ 下的大多数领域文件都与官方 API Hub 的 endpoints.json 清单保持一致。请将这些文件视为本地方法/路径发现的事实来源。

遇到问题？

• 从预检检查开始 → 5 分钟运行手册
• 401 Unauthorized → 身份验证流程（检查令牌是否过期、作用域）
• 429 Too Many Requests → 速率限制策略
• 错误代码 → 常见错误
• 分页问题 → 常见问题
• 未收到 webhook → Webhook 服务
• 来自论坛的常见问题 → 论坛热门问题
• 令牌/作用域故障 → 令牌与作用域操作手册

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

• Webhook 服务 - 使用 Express.js 构建的服务器，支持 CRC 验证
• 录制流水线 - 通过 webhook 事件自动下载

快速开始

获取访问令牌（Server-to-Server 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（Beta）	通过 v3/graphql 提供灵活的单端点查询
AI Companion	会议摘要、转录文本和 AI 生成的内容
AI 服务	通过经 Build 平台 JWT 认证的端点提供 Scribe 转录、Summarizer 转录摘要和 Translator 文本翻译

前提条件

• Zoom 账户（免费版可访问 API，但速率限制较低）
• 在 Zoom App Marketplace 注册的应用
• OAuth 凭据（Server-to-Server OAuth 或 General App OAuth/客户端凭据）
• 目标端点所需的相应作用域

需要先创建或验证应用？ 在实现 REST 调用前，请使用 Marketplace 应用管理。 其中介绍了 General App 清单、S2S 推出过程中的注意事项、应用自有的 client_credentials 作用域、 事件订阅设置、凭据响应格式，以及必须先手动创建一个初始应用，之后应用创建 API 才能授权创建其他应用的要求。 如需自动化，请从机器可读的 Marketplace 模板索引中选择， 并在更改现有 General App 时遵循清单更新工作流。

需要身份验证方面的帮助？ 请参阅 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 关键字的使用规则

• General App 用户级作用域令牌：对于当前用户端点，必须使用 me，而不是 userId（否则会报令牌无效错误）
• Server-to-Server OAuth 应用：不得使用 me，必须提供实际的 userId 或电子邮件地址
• General App 管理员级/账户级作用域令牌：可根据端点和已授予的作用域，使用 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 重置）。执行批量操作时，请分散到不同的主持用户。

⚠️ 下载 URL 需要身份验证并会重定向

录制内容的 download_url 值需要 Bearer 令牌身份验证，并且可能会重定向。请始终跟随重定向：

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

使用 Webhook 代替轮询

// 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 设置详情： 如需全面了解 Webhook 的实现，请参阅 zoom-webhooks 技能。

完整文档库

此技能包含按类别整理的全面指南：

核心概念

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

完整示例

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

故障排除

• 常见错误 - HTTP 状态码、Zoom 错误代码、错误响应格式
• 常见问题 - 速率限制、令牌刷新、分页问题、易踩的坑

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

核心 API

• references/meetings.md - 会议 CRUD、类型、设置
• 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 - 服务质量订阅

高级

• 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** - 白板 API
• references/video-management.md - 视频管理 API
• references/video-sdk-api.md - Video SDK REST API
• references/marketplace-apps.md - Marketplace 应用管理
• references/marketplace-app-templates.md - 按场景选择并自定义可直接用于 POST 的 Marketplace 应用模板
• references/marketplace-manifest-update-workflow.md - 对现有 General App 清单进行完全替换式更新
• references/marketplace-connect-actions-triggers.md - Connect 路由、外部 MCP、自定义操作和内置触发器片段
• assets/marketplace-apps/marketplace-manifest-template-index.json - 机器可读的应用类型与模板兼容性目录
• 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
General App 用户 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 集合：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

   • Server-to-Server OAuth（后端自动化）
   • 需要时使用带 PKCE 的 General App 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. 电话参考 - 电话 API 端点
2. 速率限制策略 - 单独的 Phone 速率限制

---

最重要的文档

1. API 架构（基础）

concepts/api-architecture.md

进行任何 API 调用前都必须了解的知识：

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

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

concepts/rate-limiting-strategy.md

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

• Free：轻量级 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 关键字在不同应用类型中的行为不同

   • General App 用户级令牌：必须使用 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 架构 - General App 用户级令牌必须使用 me

“如何对结果进行分页？”

→ 常见问题 - 使用 next_page_token

“没有收到 Webhook”

→ Webhook 服务 - 必须进行 CRC 验证

“录制内容下载失败”

→ 录制流程 - 使用 Bearer 身份验证并遵循重定向

“如何创建会议？”

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

---

相关技能

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

---

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

环境变量

• 有关标准化 .env 键及各值的获取位置，请参见 references/environment-variables.md。