Zoom の Incoming Webhook チャットボットの使用

Incoming Webhook アプリを使用すると、Amazon CloudWatch などの外部サービスから Zoom Team Chat チャネルに直接メッセージを送信できます。任意のチャネルでチャットアプリを使用し、独自のエンドポイントと認証トークンを生成してください。この認証情報を使用すると、HTTP POST リクエストを通じて Zoom Team Chat チャネルにメッセージを送信できます。

この記事では、次の項目について説明します。

Incoming Webhook を追加および設定する方法
- Zoom アプリマーケットプレイスから追加する
- Incoming Webhook チャットボットを設定する
Zoom Team Chat にメッセージを送信する方法
Incoming Webhook チャットボットを使用する方法
- 使用可能なコマンド
- 画像付きメッセージを送信する方法の例
Incoming Webhook チャットボットを削除する方法

Incoming Webhook チャットボットを使用するための前提条件

プロ、ビジネス、教育機関向け、またはエンタープライズアカウント
アカウントオーナーまたは管理者の特権
トークンとエンドポイントを使用した HTTP POST リクエストの送信に馴染みがあること
Zoom アプリマーケットプレイスで Incoming Webhook チャットボットを使用することに対する管理者からの承認
注: アプリが事前承認を受けていない場合は、Zoom 管理者にお問い合わせください。詳細情報については、管理者のアプリ承認の説明をご覧ください。

Incoming Webhook を追加および設定する方法

Zoom アプリマーケットプレイスから追加する

Incoming Webhook チャットボットを追加し、設定するには、Zoom アカウントの管理者権限を持っている必要があります。

アカウント管理者として Zoom アプリマーケットプレイスにサインインします。
ウィンドウの右上で Incoming Webhook を検索します。
検索結果から Incoming Webhook アプリを探してクリックします。
注: アプリが事前承認を受けていない場合は、Zoom 管理者に連絡し、アカウント用にこのアプリの承認を受けてください。詳細情報については、管理者のアプリ承認の説明をご覧ください。
[追加] をクリックします。
アプリに必要な権限を確認して [許可] をクリックします。
以上で Incoming Webhook アプリが追加されます。

Incoming Webhook チャットボットを設定する

Zoom デスクトップクライアントにサインインします。
[チームチャット] タブをクリックします。
[アプリ] で Incoming Webhook を探して選択するか、メッセージを受信するチャットチャネルを上から選択します。
新しく接続するには、次のコマンドのいずれかを入力します。
- /inc connect <connectionName: 新しく接続を確立して、1 対 1 のチャットメッセージを使用し、以下の詳細を応答します。
  - エンドポイント
  - 認証トークン
  - サンプル cURL リクエスト
- /inc connect -s <connectionName: 新しく署名付きの安全な接続を確立して、1 対 1 のチャットメッセージを使用し、以下の詳細を応答します。
  - エンドポイント
  - 秘密
  - サンプル cURL リクエスト

この情報を使用して POST リクエストを送信できます。
注: Incoming Webhook チャットボットでメッセージ送信先にするチャネルごとに、以上の手順を実行する必要があります。

Zoom Team Chat にメッセージを送信する方法

新しく接続を確立した後で、連携のエンドポイントに POST リクエストの送信を開始できます。必ず POST リクエストに承認ヘッダへの認証トークンを組み込んでください。
注: エンドポイントは POST リクエストのみ受け入れます。

接続テストには、Terminal または open git-bash（または cURL コマンドをサポートする同様の記述）を使用する方法があります。 Incoming Webhook チャットボットから届いた最初の 1 対 1 のチャットメッセージからサンプル cURL をコピーし、cURL リクエストを送信することもできます。送信が完了すると、指定したチャネルに送信したテストメッセージが表示されます。テストが成功した場合は「200 OK」という応答があります。

署名付き接続の場合、次の書式で署名を作成する必要があります。

base64UrlEncode(HMACSHA256({format}&${timestamp}&${input message}, secret))

timestamp: ミリ秒単位、30 分で期限切れ

例:

echo -n "{format}&{timestamp}&{input message}" | openssl dgst -sha256 -hmac {secret} -binary | base64

Incoming Webhook チャットボットを使用してメッセージを送信するときは、メッセージのタイプと複雑度が異なる次の 6 種類のオプションから選択できます。

メッセージの形式: この形式では、確立した接続からのプレーンテキストを送信できます。コンテンツは body に文字列として組み込んで送信する必要があります。この形式を使用するには、クエリパラメータ内に format として message を追加（?format=message）します。
```
POST <endpoint>?format=message
Authorization: <verificationToken>
Content-Type: application/json
Body: "This is a test message."
```
フィールド形式: この形式では、フィールドを使用した簡易記述形式を送信できます。たとえばメッセージをフィールド形式で記述できます。この形式を使用するには、クエリパラメータ内に format として fields を追加（?format=fields）します。
```
POST <endpoint>?format=fields
Authorization: <verificationToken>
Content-Type: application/json
Body:
{
"Field 1": "bar",
"Field 2": "qux"
}
```
リスト形式: この形式では、リストを使用した簡易記述形式を送信できます。たとえばメッセージをリスト形式で記述できます。この形式を使用するには、クエリパラメータ内に format として list を追加（?format=list）します。
```
POST <endpoint>?format=list
Authorization: <verificationToken>
Content-Type: application/json
Body:
{
"Item 1": "Item 1",
"Item 2": "Item 2"
}
```
フル形式: この形式では、リッチメッセージ形式を生成し、Zoom Team Chat メッセージで送信することができます。この形式の場合、チャットボットメッセージにヘッダ、サブヘッダ、リンク、ボタン、ドロップダウン、添付ファイルなどを使用できます。この形式を使用するには、クエリパラメータ内に format として full を追加（?format=full）する必要があります。サポート対象の JSON オブジェクトの詳細情報については、こちらのデベロッパー向けドキュメントをご覧ください。
```
POST <endpoint>?format=full
Authorization: <verificationToken>
Content-Type: application/json
Body:
{supported JSON object}
```
アップロード形式: この形式では、UploadLink、UploadToken、UploadUserId など、ファイルのアップロードに必要な情報を取得できます。この形式を使用するには、クエリパラメータ内に format として upload を追加（?format=upload）する必要があります。 body には何も追加する必要はありません。
注: これには署名付き接続が必要です。
```
POST <endpoint>?format=upload
Authorization: <verificationToken>
Content-Type: application/json
```
画像形式: この形式では、メッセージで画像を送信できます。この形式を使用するには、クエリパラメータ内に format として img を追加（?format=full）する必要があります。
注: これには署名付き接続が必要です。
```
POST <endpoint>?format=img
Authorization: <verificationToken>
Content-Type: application/json
Body:
[
{
"text":"input message",
"img":["file1","file2"]
}
]
```

Incoming webhook チャットボットを使用する方法

使用可能なコマンド

/inc connect: 現在のチャットチャネルに直接メッセージを送信するために必要なエンドポイント（URL）とトークンを作成するには「/inc connect <connectionName>」と入力します（ただし <connectionName> を適切な具体名に置き換えてください）。このチャットボットは、チャネルと同様に 1 対 1 の直接メッセージもサポートします。
/inc connect -s: 署名とアクセス制御付き画像をサポートしつつエンドポイント（URL）とトークンを作成するには「/inc connect <ConnectionName>」と入力します（ただし <connectionName> を適切な具体名に置き換えてください）。
/inc regenerate: 指定した接続の認証トークンを再生成するには、「/inc regenerate <connectionName>」と入力します（ただし <ConnectionName> を適切な具体名に置き換えてください）。
/inc disconnect: 指定した接続を削除するには「/inc disconnect <connectionName>」と入力します（ただし <ConnectionName> を適切な具体名に置き換えてください）。
/inc disconnect all: Incoming Webhook のあらゆるチャネルの接続を全面的に削除するには「/inc disconnect all」と入力します。
/inc configure: 現在のチャットチャネルのあらゆる接続を一覧表示するには「 /inc configure」と入力します。
/inc configure all: チャネル内のあらゆる接続を一覧表示するには「/inc configure all」と入力します。
/inc admin: 管理ページを開くためのリンクを取得するには「/inc admin」と入力します。

画像付きメッセージを送信する方法の例

アップロード形式でメッセージを送信し、アップロード情報を取得する

curl 'https://integrations.zoom.us/chat/webhooks/incomingwebhook/dSUcla-dQaGYgqGuBk3BsQ?format=upload&timestamp={timestamp}' -X POST -H 'Authorization: {authorization}'

取得したアップロード情報で画像をアップロードし、応答ヘッダ Zoom-File-ID でファイル ID を返す

curl '{uploadLink}' -i -F file=@{path} -X POST -H 'Authorization: Bearer {uploadToken}' -H 'Zoom-File-Meta: {"ownerType":"user","ownerId":"{userId}"}'

アップロード済みファイル ID と一緒に画像形式メッセージを送信する

curl 'https://gointegrations.zoom.us/chat/webhooks/incomingwebhook/dSUcla-dQaGYgqGuBk3BsQ?format=img&timestamp={timestamp}' -X POST -H 'Authorization: {authorization}' -H 'Content-Type: application/json' -d '[{"text":"input message","img":["fileId1","fileId2"]}]'

Incoming webhook チャットボットを削除する方法

アカウント管理者として Zoom アプリマーケットプレイスにサインインします。
ページの右上にある [管理] をクリックします。
ナビゲーションメニューで、[追加されたアプリ] をクリックします。
[Incoming WebHook] アプリの横にある [削除] をクリックします。
ダイアログを確認して、[削除] をクリックします。
注: このステップを実行すると、Zoom Team Chat 内のアクティブな接続もすべて削除されます。

追加のサポートについては、Zoom サポートまでリクエストを送信してください。