Voice API ウェブフック リファレンス

VonageはVoice APIと共にWebhookを使用し、アプリケーションが通話とやり取りできるようにします。Webhook エンドポイントは、必須が 2 つ、オプションが 1 つあります：

• アンサーウェブフック は、通話に応答したときに送信される。これは着信と発信の両方に適用される。
• イベント・ウェブフック は、通話中に発生するすべてのイベントに対して送信される。アプリケーションは、各イベントタイプをログに記録したり、対応したり、無視したりできる。
• フォールバックURL は、アンサーまたはイベントウェブフックが失敗するか、HTTP エラーステータスを返すときに使用されます。
• エラー が発生した場合、イベント・ウェブフック・エンドポイントにも配信される。

より一般的な情報については、以下をご覧ください。 ウェブフックガイド.

署名入りウェブフック

署名付きWebhookは、リクエストがVonageからのものであり、そのペイロードが転送中に改ざんされていないことを検証する方法です。Voice APIだけでなく メッセージ そして 派遣 APIは、デフォルトで署名付きコールバックをサポートしている。参照 署名付きウェブフックのデコード を参照して、入力されるJWTシグネチャをデコードする方法を学んでください。

アンサーウェブフック

着信に応答すると、HTTPリクエストが answer_url アプリケーションの設定時に指定したものです。発信の場合は answer_url 電話をかけるとき

デフォルトでは、アンサーウェブフックは GET リクエストにオーバーライドすることができる。 POST を設定することで answer_method フィールドで設定します。着信通話の場合、これらの値はアプリケーションの作成時に設定します。発信の場合は、発信時にこれらの値を指定します。

Webhookのデータフィールドに答える

SIPヘッダーによる追加データの送信

上記のフィールドに加えて、SIP Connectを使用する際に必要な追加のヘッダーを指定できます。指定するヘッダは X- に送信されます。 answer_url の接頭辞を持つ SipHeader_.例えば X-UserId の値を持つ。 1938ND9Vonageは次のようになる。 SipHeader_X-UserId=1938ND9 へのリクエストに応じる。 answer_url.

Vonageは次の両方をサポートしています。 X- ヘッダと ユーザー間 ヘッダーを使用する。これらのメカニズムは、個別に使用することも、同じ呼内で併用することもできる。

User-to-Userヘッダーは、通話中にSIP機器からVoice APIアプリケーションにコンテキストデータを送信することを可能にします。このヘッダーを使用するには、SIP機器からProgrammable SIPドメインにUser-to-Userヘッダーを送信する必要があります。さらに、Voice APIアプリケーションは、このヘッダーのコンテンツを含むアンサーウェブフックを受信する必要があります。

について ユーザー間ヘッダー は次のような書式でなければならない： SipHeader_User-to-User=1234567890abcdef;encoding=hex

アンサーウェブフックデータフィールドの例

の場合 GET リクエストの場合、変数はURLの中にある：

/answer.php?to=442079460000&from=447700900000&conversation_uuid=CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab&uuid=aaaaaaaa-bbbb-cccc-dddd-0123456789ab&SipHeader_X-UserId=1938ND9

を設定した場合 answer_method への POST とすると、ボディにJSON形式のデータを含むリクエストを受け取ることになる：

{
  "from": "442079460000",
  "to": "447700900000",
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "SipHeader_X-UserId": "1938ND9"
}

アンサーウェブフックへの応答

Vonageは、あなたが エヌシーシーオー 実行するアクションをJSON形式で記述する。

イベント・ウェブフック

イベントウェブフックHTTPリクエストは、コールのステータスが変更されると、イベントウェブフックエンドポイントに到着します。 URLは event_url アプリケーションを作成するときに指定したものです。 event_url 通話を開始するとき。

デフォルトでは、受信リクエストは POST リクエストをJSONボディで返します。 このメソッドをオーバーライドして GET を設定することで event_method に加えて event_url. システムがHTTPリクエストに応答することが期待されます。 システムがイベントを認識しないか、代わりに429、502、503、または504で応答した場合、再試行が試みられます。 NCCOを返す必要があるイベントの場合、フォールバックURLが使用されます。参照 フォールバックURL セクションを参照されたい。

含まれるデータの形式は、どのイベントが発生したかによって異なる：

• started
• ringing
• answered
• busy
• cancelled
• unanswered
• disconnected
• rejected
• failed
• human/machine
• timeout
• completed
• record
• input
• transfer

スタート

呼が作成されたことを示す。

イベントウェブフック一覧へ戻る

呼び出し音

通話先が鳴っている。

イベントウェブフック一覧へ戻る

回答済み

電話がつながった。

イベントウェブフック一覧へ戻る

忙しい

相手先は他の通話相手と通話中です。

イベントウェブフック一覧へ戻る

キャンセル

発信コールは、応答される前に発信者によってキャンセルされる。

イベントウェブフック一覧へ戻る

未回答

受信者に連絡がつかないか、受信者が着信を拒否した。

イベントウェブフック一覧へ戻る

切断

WebSocket接続が何らかの理由でアプリケーション側から切断された場合、切断イベント・コールバックが送信され、レスポンスにNCCOが含まれている場合はこれが処理され、NCCOが存在しない場合は通常の実行が継続されます。

イベントウェブフック一覧へ戻る

不採用

電話がつながる前にVonageに拒否された。

イベントウェブフック一覧へ戻る

失敗

発信に失敗しました。

イベントウェブフック一覧へ戻る

人間／機械

プログラムによって発信されたコールに対して machine_detection オプションが設定されている場合、ステータスが human または machine が送信される。

イベントウェブフック一覧へ戻る

タイムアウト

リンギング・フェーズの継続時間が、指定された ringing_timeout 期間中、このイベントが送信される。

イベントウェブフック一覧へ戻る

完成

このイベントには、通話に関するサマリーデータも含まれる。

イベントウェブフック一覧へ戻る

記録

このウェブフックは、"record "アクションを持つNCCOが終了したときに届きます。recordアクションを作成するときに、別の eventUrl を指定します。これは、このイベントタイプを処理するために別のコードを使用したい場合に便利です。

トランスクリプション

イベントウェブフック一覧へ戻る

インプット

このWebhookは、アクションが "input "のNCCOが終了したときにVonageから送信されます。

DTMFキャプチャー結果

音声認識結果

トランスクリプト・テキスト

に示すペイロードの完全な例も参照のこと。 NCCOリファレンス

イベントウェブフック一覧へ戻る

譲渡

このWebhookは、レッグがある会話から別の会話に転送されたときにVonageから送信されます。これはNCCOまたは transfer アクション

イベントウェブフック一覧へ戻る

フォールバックURL

フォールバック Webhook は、アンサー Webhook またはイベント Webhook のいずれかが、イベントが NCCO で応答すると予想されるときに、HTTP エラー・ステータスを返すか、到達不能な場合にアクセスされます。フォールバック URL から返されるデータは、元のアンサー URL またはイベント URL で受信されるものと同じですが、2 つの新しいパラメータが追加されます、 reason そして original_request:

{
  "reason": "Connection closed.",
  "original_request": {
    "url": "https://api.example.com/webhooks/event",
    "type": "event"
  }
}

接続のクローズやリセット、タイムアウト、HTTPステータスコード 429, 503 または 504 最初のNCCOでは answer_url が2回試みられる：

1. に到達することを試みる。 fallback_answer_url 倍
2. 成功しなかった場合、通話は終了する。

接続のクローズやリセット、タイムアウト、HTTPステータスコード 429, 503 または 504 通話中に event_url NCCOを返すと予想されるイベント（例えば input または notify アクション）が2回試みられる：

1. に到達することを試みる。 fallback_answer_url 倍
2. 成功しなかった場合、通話フローを継続する

エラー

イベント・エンドポイントは、エラー発生時にウェブフックも受け取ります。これはアプリケーションをデバッグするときに便利です。