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 には、ミーティング、ユーザー、ウェビナー、録画、レポート、および Zoom プラットフォームのすべてのリソースをプログラムで管理するための 600 以上のエンドポイントがあります。

公式ドキュメント：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、ユーザー、PKCE、デバイスコード）
3. ミーティング URL と Meeting SDK - join_url と Meeting SDK の混同を避ける
4. ミーティングのライフサイクル - 作成 → 更新 → 開始 → 終了 → 削除と Webhook
5. レート制限の戦略 - プランのティア、ユーザーごとの制限、再試行パターン

リファレンス：

• ミーティング - ミーティングの CRUD、タイプ、設定
• ユーザー - ユーザーのプロビジョニングと管理
• 録画 - クラウド録画へのアクセスとダウンロード
• AI サービス - Scribe エンドポイントのインベントリと現在の AI Services のパス一覧
• GraphQL クエリ - 代替クエリ API（ベータ版）
• 統合インデックス - このファイルの下のセクションを参照してください

references/ 配下のドメインファイルの大半は、公式 API Hub の endpoints.json インベントリに準拠しています。メソッドとパスの確認には、これらのファイルをローカルの信頼できる情報源として扱ってください。

問題が発生した場合：

• まず事前確認を行います → 5 分で確認できるランブック
• 401 Unauthorized → 認証フロー（トークンの有効期限とスコープを確認）
• 429 Too Many Requests → レート制限の戦略
• エラーコード → 一般的なエラー
• ページネーションでお困りの場合 → よくある問題
• Webhook が届かない場合 → Webhook サーバー
• フォーラム由来の FAQ → フォーラムでよくある質問
• トークン／スコープのエラー → トークンとスコープのプレイブック

イベント駆動型インテグレーションを構築する場合：

• Webhook サーバー - CRC 検証を備えた Express.js サーバー
• 録画パイプライン - 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 を使用できます。

主な機能

機能	説明
ミーティング管理	ミーティングの作成、読み取り、更新、削除を、柔軟なスケジュール設定とともに行います
ユーザーのプロビジョニング	ユーザーのライフサイクル（作成、更新、無効化、削除）を自動化します
ウェビナー運用	ウェビナーの CRUD、登録者の管理、パネリストの制御を行います
クラウド録画	ファイル形式で絞り込みながら、録画の一覧表示、ダウンロード、削除を行います
レポートと分析	使用状況レポート、参加者データ、日次統計を提供します
チームチャット	チャネル管理、メッセージング、チャットボットとの連携を行います
Zoom Phone	通話管理、ボイスメール、通話ルーティングを行います
Zoom Rooms	ルーム管理、デバイス制御、スケジュール設定を行います
Webhook	100 種類以上のイベントタイプについて、リアルタイムでイベント通知を受け取ります
WebSocket	パブリックエンドポイントなしで、イベントを継続的にストリーミングします
GraphQL（ベータ版）	v3/graphql で、柔軟なクエリを単一のエンドポイントに送信できます
AI Companion	ミーティングの要約、文字起こし、AI 生成コンテンツを利用できます
AI Services / Scribe	Build プラットフォームの JWT 認証済みエンドポイントを介して、ファイルやアーカイブを文字起こしします

前提条件

• Zoom アカウント（無料プランでも API を利用できますが、レート制限はより厳しくなります）
• Zoom App Marketplace に登録したアプリ
• OAuth 認証情報（Server-to-Server OAuth または User OAuth）
• 対象エンドポイントに適したスコープ

認証についてサポートが必要ですか？ OAuth フローの実装について詳しくは、zoom-oauth スキルをご覧ください。

重要な注意事項とベストプラクティス

⚠️ JWT アプリタイプは非推奨です

JWT アプリタイプは非推奨です。Server-to-Server OAuth に移行してください。これは Video SDK で使用される JWT トークンの署名には影響せず、REST API アクセス用の Marketplace の「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 アプリ：userId の代わりに me を使用する必要があります（使用しない場合、無効なトークンエラーが発生します）
• Server-to-Server OAuth アプリ：me を使用してはいけません。実際の userId またはメールアドレスを指定してください
• アカウントレベルの OAuth アプリ：me または userId のどちらでも使用できます

⚠️ ミーティング ID と UUID — 二重エンコード

/ で始まる 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 ヘッダーを事前に監視してください。

⚠️ ユーザーごとの 1 日あたりの上限

ミーティング／ウェビナーの作成・更新操作は、ユーザーごとに1 日 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、User、PKCE、Device Code）
• レート制限の戦略 - プランごとの制限、再試行パターン、リクエストキューイング

完全な例

• ミーティングのライフサイクル - Webhook イベントを含む、作成 → 更新 → 開始 → 終了 → 削除の一連のフロー
• ユーザー管理 - ユーザーの CRUD、ページネーション付き一覧表示、一括操作
• 録画パイプライン - Webhook と API を使った録画のダウンロード
• Webhook サーバー - CRC 検証と署名検証を備えた Express.js サーバー
• GraphQL クエリ - GraphQL クエリ、ミューテーション、カーソルページネーション

トラブルシューティング

• よくあるエラー - HTTP ステータスコード、Zoom エラーコード、エラーレスポンスの形式
• よくある問題 - レート制限、トークンの更新、ページネーションの落とし穴、注意点

リファレンス（Zoom API の全ドメインを網羅する 39 ファイル）

コア 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 - 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 - タスク 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/commerce.md - コマースおよび請求 API
• references/contact-center.md - コンタクトセンター 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 トークン	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 プレイグラウンド: 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

   • サーバー間 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 イベント）

REST の代わりに GraphQL を使いたい

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

レート制限はアカウント単位で設定され、すべてのアプリで共有されます。

• Free：Light は 1 秒あたり 4 件、Medium は 1 秒あたり 2 件、Heavy は 1 秒あたり 1 件
• Pro：Light は 1 秒あたり 30 件、Medium は 1 秒あたり 20 件、Heavy は 1 秒あたり 10 件
• Business+：Light は 1 秒あたり 80 件、Medium は 1 秒あたり 60 件、Heavy は 1 秒あたり 40 件
• ユーザー単位：1 日あたり 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. ユーザーごとに 1 日あたり 100 件のミーティングを作成できます

   • これはユーザー単位の厳格な制限であり、レート制限とは関係ありません
   • 一括操作では複数のホストユーザーに分散してください
   • 参照：レート制限の戦略

5. 特定の UUID では二重エンコードが必要です

   • / で始まる UUID、または // を含む UUID は二重エンコードする必要があります
   • 参照：API アーキテクチャ

6. ページネーションでは page_number ではなく next_page_token を使用してください

   • page_number は旧式で、段階的に廃止されています
   • 推奨される方法は next_page_token です
   • 参照：よくある問題

7. GraphQL のエンドポイントは /v2/ ではなく /v3/graphql です

   • 単一のエンドポイントで、カーソルベースのページネーションを使用します
   • レート制限はフィールド単位で適用されます（各フィールドは REST の同等の操作 1 件に相当します）
   • 参照：GraphQL クエリ

---

クイックリファレンス

「401 Unauthorized」

→ 認証フロー - トークンの期限切れ、またはスコープの誤り

「429 Too Many Requests」

→ レート制限の戦略 - ヘッダーでリセット時刻を確認

userId の使用時に「Invalid token」

→ API アーキテクチャ - User OAuth アプリでは 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 を参照してください。