build-zoom-team-chat-app

/build-zoom-team-chat-app

Zoom Team Chat 連携に関する背景情報です。ワークフローが明確になった後、特に Team Chat API と Chatbot API の違いが重要な場合に参照してください。

最初にお読みください（重要）

連携タイプは 2 種類あり、相互に置き換えることはできません。

1. Team Chat API（ユーザータイプ）

   • 認証済みの実際のユーザーとしてメッセージを送信します
   • ユーザー OAuth（authorization_code）を使用します
   • エンドポイントのファミリー：/v2/chat/users/...

2. Chatbot API（ボットタイプ）

   • ボットの ID でメッセージを送信します
   • クライアントクレデンシャル（client_credentials）を使用します
   • エンドポイントのファミリー：/v2/im/chat/messages

最初に誤ったタイプを選ぶと、認証／スコープ／エンドポイントがすべて一致せず、実装に失敗します。

公式ドキュメント：https://developers.zoom.us/docs/team-chat/
Chatbot のドキュメント：https://developers.zoom.us/docs/team-chat/chatbot/extend/
API リファレンス：https://developers.zoom.us/docs/api/rest/reference/chatbot/

クイックリンク

Team Chat を初めて使う方は、次の手順に従ってください。

1. はじめに - エンドツーエンドの最短手順（ユーザータイプとボットタイプ）
2. API を選択する - Team Chat API と Chatbot API
3. 環境のセットアップ - 認証情報、スコープ、アプリの設定
4. OAuth のセットアップ - 認証フロー全体
5. 最初のメッセージを送信する - メッセージ送信の実行可能なコード

リファレンス：

• Chatbot メッセージカード - カードコンポーネントの完全なリファレンス
• Webhook イベント - すべての Webhook イベントタイプ
• API リファレンス - エンドポイント、メソッド、パラメーター
• サンプルアプリケーション - 公式サンプルアプリ 10 個以上
• 統合インデックス - このファイルの以下のセクションを参照してください

問題が発生した場合：

• 認証エラー → OAuth のトラブルシューティング
• Webhook がイベントを受信しない → Webhook セットアップガイド
• メッセージを送信できない → よくある問題
• クイックチェックから始める → 5 分間のランブック

OAuth エンドポイントの確認：

• 認可 URL：https://zoom.us/oauth/authorize
• トークン URL：https://zoom.us/oauth/token
• /oauth/token が 404／HTML を返す場合は、https://zoom.us/oauth/token を使用してください。

インタラクティブなボットを構築しますか？

• ボタンアクション - ボタンのクリックを処理します
• フォーム送信 - フォームデータを処理します
• スラッシュコマンド - カスタムコマンドを作成します

クイック判断：どの API を使うべきですか？

ユースケース	使用する API
スクリプト／CI/CD から通知を送信する	Team Chat API
ユーザーとしてメッセージを自動送信する	Team Chat API
インタラクティブなチャットボットを構築する	Chatbot API
スラッシュコマンドに応答する	Chatbot API
ボタン／フォーム付きのメッセージを作成する	Chatbot API
ユーザーの操作を処理する	Chatbot API

Team Chat API（ユーザーレベル）

• メッセージは認証済みユーザーが送信したものとして表示されます
• ユーザー OAuth（authorization_code フロー）が必要です
• エンドポイント：POST https://api.zoom.us/v2/chat/users/me/messages
• スコープ：chat_message:write、chat_channel:read

Chatbot API（ボットレベル）

• メッセージはあなたのボットが送信したものとして表示されます
• クライアントクレデンシャルグラントが必要です
• エンドポイント：POST https://api.zoom.us/v2/im/chat/messages
• スコープ：imchat:bot（自動的に追加されます）
• リッチカード：ボタン、フォーム、ドロップダウン、画像

前提条件

システム要件

• Zoom アカウント
• アカウントオーナー、管理者、または Zoom for developers ロールが有効であること
  • 有効にするには：ユーザー管理 → ロール → ロール設定 → 高度な機能 → Zoom for developers を有効にする

Zoom アプリを作成する

1. Zoom App Marketplaceに移動します
2. 開発 → アプリを構築をクリックします
3. General App（OAuth）を選択します

⚠️ Server-to-Server OAuth は使用しないでください。S2S アプリには Chatbot／Team Chat 機能がありません。チャットボットをサポートしているのは General App（OAuth）のみです。

必要な認証情報

Zoom Marketplace → お使いのアプリ：

認証情報	場所	使用する API
Client ID	App Credentials → Development	両方の API
Client Secret	App Credentials → Development	両方の API
Account ID	App Credentials → Development	Chatbot API
Bot JID	Features → Chatbot → Bot Credentials	Chatbot API
Secret Token	Features → Team Chat Subscriptions	Chatbot API

参照：環境設定ガイドで設定手順をすべて確認できます。

クイックスタート：Team Chat API

ユーザーとしてメッセージを送信します：

// 1. Get access token via OAuth
const accessToken = await getOAuthToken(); // See examples/oauth-setup.md

// 2. Send message to channel
const response = await fetch('https://api.zoom.us/v2/chat/users/me/messages', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Hello from CI/CD pipeline!',
    to_channel: 'CHANNEL_ID'
  })
});

const data = await response.json();
// { "id": "msg_abc123", "date_time": "2024-01-15T10:30:00Z" }

完全な例：メッセージ送信ガイド

クイックスタート：Chatbot API

対話型チャットボットを構築します：

// 1. Get chatbot token (client_credentials)
async function getChatbotToken() {
  const credentials = Buffer.from(
    `${CLIENT_ID}:${CLIENT_SECRET}`
  ).toString('base64');
  
  const response = await fetch('https://zoom.us/oauth/token', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${credentials}`,
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: 'grant_type=client_credentials'
  });
  
  return (await response.json()).access_token;
}

// 2. Send chatbot message with buttons
const response = await fetch('https://api.zoom.us/v2/im/chat/messages', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    robot_jid: process.env.ZOOM_BOT_JID,
    to_jid: payload.toJid,           // From webhook
    account_id: payload.accountId,   // From webhook
    content: {
      head: {
        text: 'Build Notification',
        sub_head: { text: 'CI/CD Pipeline' }
      },
      body: [
        { type: 'message', text: 'Deployment successful!' },
        {
          type: 'fields',
          items: [
            { key: 'Branch', value: 'main' },
            { key: 'Commit', value: 'abc123' }
          ]
        },
        {
          type: 'actions',
          items: [
            { text: 'View Logs', value: 'view_logs', style: 'Primary' },
            { text: 'Dismiss', value: 'dismiss', style: 'Default' }
          ]
        }
      ]
    }
  })
});

完全な例：チャットボット設定ガイド

主な機能

Team Chat API

機能	説明
メッセージの送信	チャンネルまたはダイレクトメッセージにメッセージを投稿します
チャンネルの一覧表示	メタデータとともにユーザーのチャンネルを取得します
チャンネルの作成	公開／非公開チャンネルをプログラムで作成します
スレッド返信	スレッド内の特定のメッセージに返信します
編集／削除	メッセージを変更または削除します

Chatbot API

機能	説明
リッチメッセージカード	ヘッダー、画像、フィールド、ボタン、フォーム
スラッシュコマンド	カスタムの /commands で Webhook を呼び出します
ボタンアクション	Webhook コールバック付きの対話型ボタン
フォーム送信	フォームでユーザー入力を収集します
ドロップダウン選択	チャンネル、メンバー、日付／時刻の選択
LLM 連携	Claude、GPT などと簡単に連携できます

Webhook イベント（Chatbot API）

イベント	トリガー	使用例
bot_notification	ユーザーがボットにメッセージを送信する、またはスラッシュコマンドを使用する	コマンドを処理し、LLM と連携する
bot_installed	ボットがアカウントに追加される	ボットの状態を初期化する
interactive_message_actions	ボタンがクリックされる	ボタンアクションを処理する
chat_message.submit	フォームが送信される	フォームデータを処理する
app_deauthorized	ボットが削除される	クリーンアップする

参照：Webhook イベントリファレンス

メッセージカードのコンポーネント

次のコンポーネントを使って、リッチな対話型メッセージを作成します：

コンポーネント	説明
header	タイトルとサブタイトル
message	プレーンテキスト
fields	キーと値のペア
actions	ボタン（Primary、Danger、Default のスタイル）
section	色付きのサイドバーによるグループ化
attachments	リンク付き画像
divider	水平線
form_field	テキスト入力
dropdown	選択メニュー
date_picker	日付の選択

参照：すべてのコンポーネントの一覧はメッセージカードリファレンスをご覧ください。

アーキテクチャパターン

チャットボットのライフサイクル

User types /command → Webhook receives bot_notification
                            ↓
                     payload.cmd = "user's input"
                            ↓
                     Process command
                            ↓
                     Send response via sendChatbotMessage()

LLM 連携パターン

case 'bot_notification': {
  const { toJid, cmd, accountId } = payload;
  
  // 1. Call your LLM
  const llmResponse = await callClaude(cmd);
  
  // 2. Send response back
  await sendChatbotMessage(toJid, accountId, {
    body: [{ type: 'message', text: llmResponse }]
  });
}

参照：LLM 連携ガイド

サンプルアプリケーション

サンプル	説明	リンク
チャットボット クイックスタート	公式チュートリアル（最初に読むことをおすすめします）	GitHub
Claude チャットボット	Anthropic Claude を利用した AI チャットボット	GitHub
Unsplash チャットボット	データベースを利用した画像検索	GitHub
ERP チャットボット	スケジュールされたアラート機能を備えた Oracle ERP	GitHub
タスクマネージャー	完全な CRUD アプリ	GitHub

参照：10 個すべてのサンプルの分析については、サンプルアプリケーションガイドをご覧ください。

よくある操作

チャンネルにメッセージを送信する

// Team Chat API
await fetch('https://api.zoom.us/v2/chat/users/me/messages', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` },
  body: JSON.stringify({
    message: 'Hello!',
    to_channel: 'CHANNEL_ID'
  })
});

ボタンのクリックを処理する

// Webhook handler
case 'interactive_message_actions': {
  const { actionItem, toJid, accountId } = payload;
  
  if (actionItem.value === 'approve') {
    await sendChatbotMessage(toJid, accountId, {
      body: [{ type: 'message', text: '✅ Approved!' }]
    });
  }
}

Webhook 署名を検証する

function verifyWebhook(req) {
  const message = `v0:${req.headers['x-zm-request-timestamp']}:${JSON.stringify(req.body)}`;
  const hash = crypto.createHmac('sha256', process.env.ZOOM_VERIFICATION_TOKEN)
    .update(message)
    .digest('hex');
  return req.headers['x-zm-signature'] === `v0=${hash}`;
}

デプロイ

ローカル開発での ngrok の使用

# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 4000

# Use HTTPS URL as Bot Endpoint URL in Zoom Marketplace
# Example: https://abc123.ngrok.io/webhook

本番環境へのデプロイ

参照：デプロイガイドでは、以下について説明しています。

• Nginx リバースプロキシの設定
• ベースパスの設定
• OAuth リダイレクト URI の設定

制限事項

制限	値
メッセージの長さ	4,096 文字
ファイルサイズ	512 MB
チャンネルごとのメンバー数	10,000
ユーザーごとのチャンネル数	500

セキュリティのベストプラクティス

1. Webhook 署名を検証する - 常に x-zm-signature ヘッダーを使用して検証します
2. メッセージをサニタイズする - 4096 文字までに制限し、制御文字を削除します
3. JID を検証する - 形式が user@domain または channel@domain であることを確認します
4. 環境変数を使用する - 認証情報をハードコードしないでください
5. HTTPS を使用する - 本番環境の Webhook では必須です

参照：セキュリティのベストプラクティス

ドキュメントライブラリ完全版

コアコンセプト（まずはこちら！）

• API 選択ガイド - Team Chat API と Chatbot API のどちらを選ぶか
• 環境設定 - 認証情報の完全ガイド
• 認証フロー - OAuth と Client Credentials
• Webhook アーキテクチャ - Webhook の仕組み
• メッセージカードの構造 - カードコンポーネントの階層

完全な実装例

• OAuth の設定 - OAuth の完全な実装
• メッセージの送信 - Team Chat API によるメッセージ送信
• チャットボットの設定 - Webhook を備えた完全なチャットボット
• ボタンアクション - インタラクティブなボタンの処理
• フォーム送信 - フォームデータの処理
• スラッシュコマンド - カスタムコマンドの作成
• LLM 連携 - Claude/GPT との連携
• スケジュールされたアラート - Cron と受信 Webhook
• チャンネル管理 - チャンネルの作成と管理

リファレンス

• API リファレンス - すべてのエンドポイントとメソッド
• Webhook イベント - イベントの完全なリファレンス
• メッセージカード - すべてのカードコンポーネント
• サンプルアプリケーション - 公式サンプル 10 件の分析
• エラーコード - エラー処理ガイド

トラブルシューティング

• OAuth の問題 - 認証の失敗
• Webhook の問題 - Webhook のデバッグ
• よくある問題 - 迅速な診断

リソース

• 公式ドキュメント：https://developers.zoom.us/docs/team-chat/
• API リファレンス：https://developers.zoom.us/docs/api/rest/reference/chatbot/
• 開発者フォーラム：https://devforum.zoom.us/
• アプリマーケットプレイス：https://marketplace.zoom.us/

---

お困りですか？ 完全なナビゲーションについては、以下の統合インデックスのセクションをご覧ください。

---

統合インデックス

このセクションは SKILL.md から移行されました。

Zoom Team Chat スキルの完全なナビゲーションガイドです。

クイックスタートの手順

• まずはこちら：はじめに
• トラブルシューティングを優先する場合：5 分間のランブック

手順 1：Team Chat API（ユーザーレベルのメッセージング）

ユーザーアカウントとしてメッセージを送信する場合に使用します。

1. API 選択ガイド - Team Chat API が適切か確認します
2. 環境設定 - 認証情報を取得します
3. OAuth 設定の例 - 認証を実装します
4. メッセージ送信の例 - 最初のメッセージを送信します

手順 2：Chatbot API（対話型ボット）

リッチメッセージを使った対話型チャットボットを構築する場合に使用します。

1. API 選択ガイド - Chatbot API が適切か確認します
2. 環境設定 - 認証情報（Bot JID を含む）を取得します
3. Webhook アーキテクチャ - Webhook イベントを理解します
4. チャットボット設定の例 - 最初のボットを構築します
5. メッセージカードのリファレンス - リッチメッセージを作成します

主要な概念

両方の API に必要な基本事項です。

ドキュメント	説明
API 選択ガイド	Team Chat API と Chatbot API のどちらを選ぶか
環境設定	認証情報とアプリの設定を完了します
認証フロー	OAuth と Client Credentials
Webhook アーキテクチャ	Webhook の仕組み（Chatbot API）
メッセージカードの構造	カードコンポーネントの階層
デプロイガイド	本番環境へのデプロイ戦略
セキュリティのベストプラクティス	インテグレーションを安全に保護します

実践的なサンプル

一般的なシナリオで使えるコードです。

認証

サンプル	説明
OAuth の設定	ユーザー OAuth フローの実装
トークン管理	トークンの更新、有効期限への対応

基本操作

サンプル	説明
メッセージ送信	Team Chat API によるメッセージ送信
チャットボットの設定	Webhook を使った完全なチャットボット
チャンネル一覧	ユーザーのチャンネルを取得します
チャンネル作成	パブリック／プライベートチャンネルを作成します

対話型機能（Chatbot API）

サンプル	説明
ボタンアクション	ボタンのクリックを処理します
フォーム送信	フォームデータを処理します
スラッシュコマンド	カスタムコマンドを作成します
ドロップダウン選択	チャンネル／メンバーの選択機能

高度なインテグレーション

サンプル	説明
LLM インテグレーション	Claude/GPT を統合します
スケジュール通知	Cron + 受信 Webhook
データベース連携	会話の状態を保存します
複数ステップのワークフロー	複雑なユーザー操作

リファレンス

API ドキュメント

リファレンス	説明
API リファレンス	関連情報と一般的なエンドポイント
Webhook イベント	イベントの種類と処理チェックリスト
メッセージカード	すべてのカードコンポーネント
エラーコード	エラー処理ガイド

サンプルアプリケーション

リファレンス	説明
サンプルアプリケーション	サンプルアプリの一覧／注記

フィールドガイド

リファレンス	説明
JID Formats	JID 識別子について
Scopes Reference	一般的なスコープ
Rate Limits	スロットリングのガイダンス

トラブルシューティング

ガイド	説明
Common Issues	迅速な診断と解決策
OAuth Issues	認証エラー
Webhook Issues	Webhook のデバッグ
Message Issues	メッセージ送信の問題
Deployment Issues	本番環境の問題

アーキテクチャパターン

チャットボットのライフサイクル

User Action → Webhook → Process → Response

LLM 統合パターン

User Input → Chatbot receives → Call LLM → Send response

承認ワークフローパターン

Request → Send card with buttons → User clicks → Update status → Notify

一般的なユースケース

通知

• CI/CD ビルド通知
• サーバー監視アラート
• スケジュールされたレポート
• システムの健全性チェック

ワークフロー

• 承認リクエスト
• タスクの割り当て
• ステータス更新
• フォームの送信

統合

• LLM を活用したアシスタント
• データベースクエリ
• 外部 API との統合
• ファイルや画像の共有

自動化

• スケジュールされたメッセージ
• 自動応答
• データ収集
• レポート生成

リソースリンク

公式ドキュメント

• Team Chat Docs - 公式概要
• Chatbot Docs - チャットボットガイド
• API Reference - REST API ドキュメント
• App Marketplace - アプリの作成と管理

サンプルコード

• Chatbot Quickstart - 公式チュートリアル
• Claude Chatbot - AI 統合
• Unsplash Chatbot - 画像検索ボット
• ERP Chatbot - エンタープライズ統合
• Task Manager - 完全な CRUD アプリ

ツール

• App Card Builder - ビジュアルカードデザイナー
• ngrok - ローカル Webhook テスト
• Postman - API テスト

コミュニティ

• Developer Forum - 質問する
• GitHub Discussions - コミュニティサポート
• Developer Support - 公式サポート

ドキュメントの状況

✅ 完了

• メインの skill.md エントリーポイント
• API 選択ガイド
• 環境設定
• Webhook アーキテクチャ
• チャットボット設定例（動作するコード一式）
• メッセージカードのリファレンス
• 一般的な問題のトラブルシューティング

📝 保留中（優先度高）

• OAuth 設定例
• メッセージ送信例
• ボタンアクションの例
• LLM 統合例
• Webhook イベントのリファレンス
• API リファレンス
• サンプルアプリケーションの分析

📋 計画中（優先度低）

• フォーム送信例
• チャンネル管理の例
• データベース統合例
• エラーコードのリファレンス
• レート制限ガイド
• デプロイのトラブルシューティング

はじめにチェックリスト

Team Chat API の場合

• API 選択ガイドを読む
• 環境設定を完了する
• Client ID と Client Secret を取得する
• 必要なスコープを追加する
• OAuth フローを実装する
• 最初のメッセージを送信する

Chatbot API の場合

• API 選択ガイドを読む
• 環境設定を完了する
• Client ID、Client Secret、Bot JID、Secret Token、Account ID を取得する
• Features で Team Chat を有効にする
• Bot Endpoint URL と Slash Command を設定する
• ローカルテスト用に ngrok を設定する
• Webhook ハンドラーを実装する
• 最初のチャットボットメッセージを送信する

バージョン履歴

• v1.0 (2026-02-09) - 包括的なドキュメントの初版
  • 基本概念（API の選択、環境設定、Webhook）
  • チャットボットのセットアップ例一式
  • メッセージカードのリファレンス
  • よくある問題のトラブルシューティング

サポート

Team Chat API の選択、セットアップ、例、トラブルシューティングのナビゲーションハブとして、この SKILL.md を使用してください。

環境変数

• 標準化された .env キーと各値の確認場所については、references/environment-variables.md を参照してください。