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のデータフィールドに答える

フィールド 例 説明
to 442079460000 電話に出た番号。(これは、お客様の アプリケーション.)
from 447700900000 電話をかけてきたNumbers to.これは、固定電話や携帯電話の番号、またはプログラムによって発信された場合は別のバーチャル番号になります。
from_user JaneDoe を呼び出したユーザー名 to Client SDKを使用して呼び出された場合のみ。この場合 from は不在となる（つまり、 from そして from_user が同時に存在することはない）。
endpoint_type phone 通話に応答した音声チャネルのタイプ。指定可能な値は以下のとおり。 phone, sip, websocket, app, vbc.
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼び出しの一意の識別子
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
region_url https://api-ap-3.vonage.com で呼び出しを制御するために使用する地域APIエンドポイント。 REST API全地域リストを見る これ
custom_data { "key": "value" } カスタムデータオブジェクト。 serverCall メソッドを使ってアプリケーションから呼び出されたとき。 Client SDK

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

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

警告だ： で始まるヘッダー X-Nexmo には送信されません。 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

User-to-Userヘッダーは、それが有効な文字を含み、256文字を超えないこと を保証するためだけに検証される。コンテンツ自体はそれ以外には検証されない。

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

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

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

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

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

イベント・ウェブフック

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

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

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

スタート

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

フィールド 例 説明
from 442079460000 発信元番号
to 447700900000 発信先番号
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼び出しの一意の識別子
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
status started 通話状況
direction outbound 呼び出しの方向は以下のいずれかである。 inbound または outbound
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）

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

呼び出し音

通話先が鳴っている。

フィールド 例 説明
from 442079460000 発信元番号
to 447700900000 発信先番号
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼び出しの一意の識別子
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
status ringing 通話状況
direction outbound 呼び出しの方向は以下のいずれかである。 inbound または outbound
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）

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

回答済み

電話がつながった。

フィールド 例 説明
start_time null このフィールドは現在サポートされていない。
rate 0.12 通話料金（ユーロ
from 442079460000 発信元番号
to 447700900000 発信先番号
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼び出しの一意の識別子
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
status answered 通話状況
direction inbound 呼び出しの方向は以下のいずれかである。 inbound または outbound
network null 通話で使用されたネットワークの種類
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）

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

忙しい

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

フィールド 例 説明
from 442079460000 発信元番号
to 447700900000 発信先番号
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼び出しの一意の識別子
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
status busy 通話状況
direction outbound コール・ディレクション outbound そこで
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）
sip_code 404 返されたSIPステータスコード(例、 404, 480あるいは 487)を経由して、登録された event_urlこれは、呼の完了または失敗の理由についての付加的な詳細を提供する。以下のSIPステータスコードを参照のこと。 これ.

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

キャンセル

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

フィールド 例 説明
from 442079460000 発信元番号
to 447700900000 発信先番号
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼び出しの一意の識別子
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
status cancelled 通話状況
direction outbound コール・ディレクション outbound そこで
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）

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

未回答

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

フィールド 例 説明
from 442079460000 発信元番号
to 447700900000 発信先番号
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼び出しの一意の識別子
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
status unanswered 通話状況
detail unavailable 加入者が一時的に利用できないことを示す (unavailable)、またはキャリアが適切な時間内に応答を返せなかった(timeout)
direction outbound コール・ディレクション outbound そこで
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）
sip_code 404 返されたSIPステータスコード(例、 404, 480あるいは 487)を経由して、登録された event_urlこれは、呼の完了または失敗の理由についての付加的な詳細を提供する。以下のSIPステータスコードを参照のこと。 これ.

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

切断

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

フィールド 例 説明
from 442079460000 発信元番号
to 447700900000 発信先番号
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼び出しの一意の識別子
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
status disconnected 通話状況
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）

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

不採用

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

フィールド 例 説明
from 442079460000 発信元番号
to 447700900000 発信先番号
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼び出しの一意の識別子
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
status rejected 通話状況
detail restricted を示す。 to または from Numbers は無効です (invalid_number)、キャリアによる着信拒否(restricted)、または着呼側によって拒否された(declined)
direction outbound コール・ディレクション outbound そこで
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）
sip_code 404 返されたSIPステータスコード(例、 404, 480あるいは 487)を経由して、登録された event_urlこれは、呼の完了または失敗の理由についての付加的な詳細を提供する。以下のSIPステータスコードを参照のこと。 これ.

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

失敗

発信に失敗しました。

フィールド 例 説明
from 442079460000 発信元番号
to 447700900000 発信先番号
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼び出しの一意の識別子
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
status failed 通話状況
detail cannot_route 宛先がそのアカウントでサポートされていないか、ブロックされていることを示します (cannot_route)、Numbersは利用できない(number_out_of_service) またはサーバーエラーが発生した (internal_error)
direction outbound コール・ディレクション outbound そこで
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）
sip_code 404 返されたSIPステータスコード(例、 404, 480あるいは 487)を経由して、登録された event_urlこれは、呼の完了または失敗の理由についての付加的な詳細を提供する。以下のSIPステータスコードを参照のこと。 これ.

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

人間／機械

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

フィールド 例 説明
call_uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼び出しの一意の識別子 (注 call_uuidではない。 uuid 他のエンドポイントと同様)
from 442079460000 発信元番号
to 447700900000 発信先番号
status human 通話状態は以下のいずれかである。 human と答えたか machine ボイスメールまたは他の自動応答サービスによって通話に応答された場合
sub_state beep_start ボイスメール、またはファクスで通話に応答し、ビープ音が検出された場合の、高度な機械検出ステータス。設定可能な値は beep_start ボイスメール fax ファックス用 beep_timeout.
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）

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

タイムアウト

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

フィールド 例 説明
from 442079460000 発信元番号
to 447700900000 発信先番号
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼び出しの一意の識別子
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
status timeout 通話状況
direction outbound コール・ディレクション outbound そこで
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）

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

完成

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

フィールド 例 説明
end_time 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼び出しの一意の識別子
network GB-FIXED 通話で使用されたネットワークの種類
duration 2 通話時間（秒）
start_time 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）
rate 0.00450000 1分あたりの通話料金 (EUR)
price 0.00015000 通話料金合計（ユーロ）
from 442079460000 発信元番号
to 447700900000 発信先番号
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
status completed 通話状況
direction インバウンド 呼び出しの方向は以下のいずれかである。 inbound または outbound
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）
disconnected_by user 2つの値のいずれかを指定する：
platform - 例えば、NCCOが最後のアクションを終了し、通話が切断された場合などです。
user - ユーザーが通話を切断した、通話を拒否した、または応答しなかったなど。
sip_code 404 返されたSIPステータスコード(例、 404, 480あるいは 487)を経由して、登録された event_urlこれは、呼の完了または失敗の理由についての付加的な詳細を提供する。以下のSIPステータスコードを参照のこと。 これ.

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

記録

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

フィールド 例 説明
start_time 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）
recording_url https://api.nexmo.com/v1/files/bbbbbbbb-aaaa-cccc-dddd-0123456789ab 録画のダウンロード
size 12222 録画ファイルのサイズ（バイト単位）
recording_uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この録音に固有の識別子
end_time 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）

トランスクリプション

フィールド 例 説明
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
type record レコード型のNCCOアクション
recording_uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この録音に固有の識別子
status transcribed テープ起こし状況
transcription_url https://api.nexmo.com/v1/files/bbbbbbbb-aaaa-cccc-dddd-0123456789ab 録音テープ起こしファイルのURL

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

インプット

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

フィールド 例 説明
from 447700900000 発信元番号
to 447700900000 発信先番号
dtmf 下記参照 DTMFキャプチャ結果
speech 下記参照 音声認識結果
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼の一意の識別子。入力がDTMFタイムアウトに達すると、このプロパティは表示されないかもしれない。
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）

DTMFキャプチャー結果

フィールド 例 説明
digits 42 ユーザーが押したボタン
timed_out true DTMF入力がタイムアウトしたかどうか： true もしそうなら false そうでなければ

音声認識結果

フィールド 例 説明
timeout_reason end_on_silence_timeout ユーザーが話すのを止めたときに入力が終了したかどうかを示す (end_on_silence_timeout)、最大継続時間タイムアウト(max_duration)、またはユーザーが何も言わなかった場合(start_timeout)
results 下記参照 配列 認識されたテキストオブジェクト
error ERR1: Failed to analyze audio エラーメッセージ。
recording_url https://api-us.nexmo.com/v1/files/eeeeeee-ffff-0123-4567-0123456789ab スピーチ録音。以下を含む saveAudio フラグが true での input アクションが必要です。ダウンロードにはJWT認証が必要です。 録音をダウンロードする.
トランスクリプト・テキスト
フィールド 例 説明
text sales ユーザーが話した言葉を表すトランスクリプトテキスト。
confidence 0.9405097 0.0から1.0の間の信頼度。数字が大きいほど、認識された単語が正しい可能性が高いと推定されます。

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

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

譲渡

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

フィールド 例 説明
conversation_uuid_from CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab その足が元々持っていた会話ID
conversation_uuid_to CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab 脚を移した先の会話ID
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab この呼び出しの一意の識別子
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）

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

フォールバックURL

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

接続のクローズやリセット、タイムアウト、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. 成功しなかった場合、通話フローを継続する

エラー

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

フィールド 例 説明
reason Syntax error in NCCO. Invalid value type or action. エラーの内容に関する情報
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab この会話に固有の識別子
timestamp 2020-01-01T12:00:00.000Z タイムスタンプ（ISO 8601形式）