オーディオウェブフックの定義

この機能は現在、電話統合のGenesys Audio Connectorでのみサポートされています。

オーディオWebhookは、オーディオを収集するためにrecordレスポンスタイプが使用されるたびに、外部サービスまたはアプリケーションを呼び出します。外部サービスは音声を処理し、エラーが発生した場合は通話を切断する。 AIアシスタントは音声を保存しないため、コンプライアンス上の理由から、音声ウェブフックを使用して音声を保存することがよくあります。

開始前に

外部サービスへのプログラマチック呼び出しは、以下の要件を満たす必要があります。

呼び出しは POST HTTP 要求であること。
リクエストボディはJSONオブジェクト（Content-Type: multipart/form-data）でなければなりません。
コールは30秒以内に戻らなければならない。

音声録音の詳細については、発呼者の発話を録音するを参照してください。

手順

Web フックの詳細を追加するには、以下の手順を実行します。

ホーム > 環境へ。
「下書き 」タブ > 「下書き環境 」または「公開」タブ > 「公開環境 」のいずれかから 、「設定 」をクリックします。
Audio webhookをクリックします。
Audio webhook スイッチを Enabled に設定します。
フィールドに URL フィールドに、 HTTP POST リクエストを送信する外部アプリケーションの URL を追加します。 URL が SSL プロトコル（例：URL が https で始まるもの）を使用していることを確認してください。
Secret フィールドに、外部サービスと認証するためにリクエストと一緒に渡す秘密鍵を追加します。キーはテキスト文字列（例えば、紫のユニコーン）で指定する必要があり、最大長は1,024文字である。

コンテキスト変数を指定することはできません。外部サービスがトークンを必要としない場合は、任意の文字列を指定してください。このフィールドを空のままにすることはできません。入力中にパスワードを表示するには、入力前に「 パスワードを表示 」をクリックします。秘密を保存した後、文字列はアスタリスクに置き換えられ、再び見ることはできません。このフィールドの使用方法の詳細については、クラシック・エクスペリエンス専用のWebhook セキュリティを参照してください。

Timeout フィールドで、アシスタントがエラーを返す前にWebhookからの応答を待つ時間（秒）を指定します。タイムアウト時間は1秒から30秒の間でなければならない。
「ヘッダー」セクションで、「ヘッダーの追加 (Add header)」をクリックし、サービスに渡すヘッダーを 1 つずつ追加します。

例えば、あなたが呼び出した外部アプリケーションがレスポンスを返す場合、そのアプリケーションは複数のフォーマットでレスポンスを送信できるかもしれない。 Webhook では、応答が JSON でフォーマットされている必要があります。以下の表は、結果として返される値がJSON形式であることを保証するためのヘッダーの追加方法を示している。

表 1. ヘッダーの例
ヘッダー名	ヘッダー値
`Content-Type`	`application/json`

ヘッダー値を保存した後、文字列はアスタリスクに置き換えられ、再び表示することはできません。

Web フックの詳細は自動的に保存されます。

その他の例については、「オーディオ Webhook の例」をご覧ください。

Webhook のテスト

実稼働環境で使用されているアシスタントに対して Web フックを有効にする前に、Web フックの広範なテストを行ってください。

Webhookは、通話中に録音応答タイプが使用されたときにトリガーされます。ウェブフックへのリクエストが失敗すると、通話は切断される。 Webhookが失敗した理由の詳細については、電話の統合ログを見ることができます。詳細については、電話統合のトラブルシューティングを参照してください。

要求本文

外部コードが処理できるように、オーディオウェブフックのリクエストボディのフォーマットを知っておくと便利です。

ペイロードには、Content-Type: multipart/form-dataとしてオーディオとメタデータが含まれる。リクエストの例はこうだ：

POST /audio-webhook HTTP/1.1
Content-Type: multipart/form-data; boundary=----------3676416B-9AD6-440C-B3C8-FC66DDC7DB45
----------3676416B-9AD6-440C-B3C8-FC66DDC7DB45
Content-Disposition: form-data; name="metadata"
Content-Type: application/json
{
    "assistant_id": "dadf4b56-3b67-411a-b48d-079806b626d3",
    "environment_id": "6205aead-fe91-44af-bfe1-b4435015ba23",
    "session_id": "50989a59-9976-4b3f-9a98-af42adcad69a",
    "recording_id": "3daeb5d2-f52b-4c3e-a869-328b6fc6327c",
    "start_timestamp": "2024-10-21T17:22:07.789Z",
    "stop_timestamp": "2024-10-21T17:22:37.789Z"
}
----------3676416B-9AD6-440C-B3C8-FC66DDC7DB45
Content-Disposition: form-data; name="audio_recording"
Content-Type: audio/mulaw;rate=8000

<binary data>