NCCOリファレンス

コールコントロールオブジェクト(NCCO)はJSON配列で表されます。これを使用して、Voice APIコールのフローを制御できます。NCCOを正しく実行するには、JSONオブジェクトが有効である必要があります。

NCCOを開発、テストしている間、Voice Playgroundを使ってインタラクティブにNCCOを試すことができます。以下のことができます。 詳しくはVoice API Overviewをご覧ください。 または ダッシュボードのボイス・プレイグラウンドに直接移動する.

NCCOの活動

NCCOにおけるアクションの順序は、コールの流れを制御する。次のアクションを実行する前に完了しなければならないアクションは以下のとおりである。 同期.その他のアクションは以下の通り。 非同期.つまり、ある条件が満たされるまで、次のアクションを継続することになっている。例えば record アクションは endOnSilence オプションが満たされる。NCCOのすべてのアクションが完了すると、コールは終了する。

NCCOのアクションと、各アクションのオプションとタイプは以下の通り:

アクション 説明 同期
記録 通話の全部または一部 いいえ
会話 既存の 会話 はい
コネクト 電話番号やVBC内線などの接続可能なエンドポイントへ。 はい
トーク 合成音声を会話に送る。 そうだ。 bargeIn=true
ストリーム オーディオファイルを会話に送信する。 そうだ。 bargeIn=true
入力 通話相手の数字や音声入力を収集します。 はい
通知 NCCOを通じて進捗状況を追跡するよう、アプリケーションにリクエストを送信する。 はい
ウェイト 指定した秒数だけ実行を一時停止する。 はい
譲渡 現在の会話から別の既存の会話にコールレッグを移動する はい

: インバウンドコールに接続する には、通話または会議が開始された後にNCCOをVonageに提供する方法の例が記載されています。

すべてのアクションにおいて eventUrl パラメータは配列でなければならない(MUST)。

記録

を使用する。 record アクションを使用して、通話または通話の一部を録音します:

[
  {
    "action": "record",
    "eventUrl": ["https://example.com/recordings"]
  },
  {
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "from":"447700900000",
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001"
      }
    ]
  }
]

記録アクションは非同期です。 同期条件を定義することができます。 endOnSilence, timeOut または endOnKey - を設定し、その条件が満たされたときに録音を終了する。 条件が設定されていない場合、録音は非同期で動作し、通話を録音しながら、即座 に次のアクションに進む。通話が終了したときのみ、録音は終了し、関連するイベントを送信する。 これは、通話モニタリングと同様のシナリオに使用される。

を使用して録音を書き写すことができます。 transcription オプション.録音テープ起こしが完了すると、コールバックが eventUrl.トランスクリプション設定を使用して、カスタムの eventUrl そして language をご利用ください。この機能は有料ですのでご注意ください。 Voice API価格 ページの「プログラマブル機能」の下にある。

ワークフローについては、以下を参照のこと。 レコーディング.

以下のオプションを使って record アクションだ:

オプション 説明 必須
format 特定のフォーマットで通話を録音します。 オプションは以下のとおり:
  • mp3
  • wav
  • ogg
デフォルト値は mp3あるいは wav 2チャンネル以上を録音する場合
いいえ
split 送信と受信のオーディオを、ステレオ録音セットの別々のチャンネルに録音する。 conversation を有効にする。 いいえ
channels 録画するチャンネル数(最大 32).参加者数がNumbersを超えた場合 channels 追加参加者はファイルの最後のチャンネルに追加される。 conversation も有効にしなければならない。 いいえ
endOnSilence n秒間の無音状態で録音を停止する。録音が停止されると録音データは event_url.可能な値の範囲は3<=である。endOnSilence<=10. いいえ
endOnKey ハンドセットで桁が押されたときに録音を停止する。設定可能な値は以下のとおりです: *, # または任意の一桁(例 9. いいえ
timeOut 録画の最大長(秒)。録音が停止されると、録音データは event_url.可能な値の範囲は 3 秒と 7200 秒(2時間)。 いいえ
beepStart に設定する。 true 録音開始時にビープ音を鳴らす。 いいえ
eventUrl 録音終了時に非同期で呼び出されるWebhookエンドポイントへのURL。メッセージ録音がVonageによってホストされている場合、このWebhookには 録画やその他のメタデータをダウンロードするために必要なURL. いいえ
eventMethod へのリクエストに使われるHTTPメソッド。 eventUrl.デフォルト値は POST. いいえ
transcription [ベータ版] 空のオブジェクトに設定する、 {}でカスタマイズすることもできる。 トランスクリプション設定 いいえ

トランスクリプション設定

オプション 説明 必須
language 言語(BCP-47 フォーマット)を使用します。これは現在、自動音声録音と同じ言語をサポートしており、リストが利用可能です。 これ. いいえ
eventUrl トランスクリプションが終了したときに非同期に呼び出されるウェブフックエンドポイントのURL。 いいえ
eventMethod へのリクエストにVonageが使用するHTTPメソッド。 イベントURL.デフォルト値は POST. いいえ
sentimentAnalysis [開発者プレビュー] 通話録音セグメントに対してセンチメント分析を実行します。各セグメントについて、-1 (否定的なセンチメント) から 1 (肯定的なセンチメント) までの値を返します。デフォルトは false. いいえ

ご注意:音声通話の書き起こしには最大2時間の制限があります。

レコード・リターン・パラメータ

参照 Webhookリファレンス に返されるレコードまたはトランスクリプションパラメータについてである。 eventUrl.

会話

を使用することができます。 conversation アクションを使用すると、通信コンテキストを保持しながら、標準またはモデレートされた会議を作成することができます。使用方法 conversation 同じ name は、同じ永続化された 会話.会話に割り当てられたバーチャルナンバーに最初に電話をかけた人が、その会話を作成する。この動作は同期的である。

200人まで招待できます。

以下の NCCO の例は、異なるタイプの Conversation をどのように設定するかを示している。この例では answer_url webhook GETリクエストのパラメータは、参加者に1つのNCCOを、モデレーターにもう1つのNCCOを確実に配信するためのものです。

[
  {
    "action": "conversation",
    "name": "nexmo-conference-standard",
    "record": true,
    "transcription": {
      "eventUrl": [ "https://example.com/transcription" ],
      "eventMethod": "POST",
      "language": "he-IL"
    }
  }
]

以下のオプションを使って 会話 アクションだ:

オプション 説明 必須
name 会話ルームの名前。アプリケーションレベルまで名前空間があります。 地域. はい
musicOnHoldUrl への URL mp3 ファイルを使用して、会話が始まるまで参加者にストリーミングします。デフォルトでは、最初の人がVoiceアプリに関連付けられたバーチャル番号に電話をかけたときに会話が始まります。モデレーターが会話に参加する前にこのmp3をストリーミングするには、次のように設定します。 開始 への 擬似 司会者以外のすべてのユーザーのために。 いいえ
startOnEnter のデフォルト値は 真の この発信者が会話に参加したときに会話が始まるようにする。 name.に設定する。 擬似 司会者の進行のもと、参加者同士が会話を交わす。 いいえ
endOnExit モデレータが電話を切ったときにモデレートされた会話が終了するかどうかを指定します。これは 擬似 これは、モデレーターがまだ通話中であるかどうかに関係なく、最後に残った参加者が電話を切ったときに会話が終了することを意味します。設定 endOnExit への 真の をクリックすると、司会者が電話を切ったときに会話が終了します。 いいえ
record に設定する。 真の をクリックして会話を録音します。標準の会話では、1人以上の参加者が会話に参加した時点で録音が開始されます。モデレートされた会話では、モデレーターが参加した時点で録画が開始されます。つまり、指定された会話でNCCOが実行された時です。 開始 に設定されている。 真の.録画が終了すると、録画をダウンロードしたURLがイベントURLに送信されます。を指定することで、デフォルトの録画イベントURLとデフォルトのHTTPメソッドをオーバーライドできます。 eventUrl そして eventMethod オプションの conversation アクションの定義
デフォルトでは、音声はMP3形式で録音されます。詳しくは レコーディング のガイドを参照されたい。
いいえ
canSpeak この参加者が聞くことができるレッグUUIDのリスト。提供されない場合、参加者は誰からも聞くことができます。空のリストが提供された場合、参加者は誰からも聞こえません。 いいえ
canHear この参加者が聞くことができるレッグUUIDのリスト。指定されていない場合、参加者は全員の声を聞くことができます。空のリストが指定された場合、参加者は他の参加者の声を聞くことができません。 いいえ
mute に設定する。 真の をクリックして参加者をミュートします。参加者の音声は会話に流れず、録音されません。使用時 canSpeakその mute パラメータはサポートされていない。 いいえ
transcription 転写の設定。(空のオブジェクトであっても)表示された場合、トランスクリプションが有効になります。recordパラメータは 真の.参照 トランスクリプション設定 詳細は上記を参照。 いいえ

接続

を使用することができます。 connect 電話番号やVBC内線などのエンドポイントにコールを接続するためのアクション。

このアクションは同期的で コネクト NCCOスタックの次のアクションが処理される。接続アクションは、呼び出し先のエンドポイントがビジーまたは使用不可の場合に終了します。接続アクションをネストすることで、エンドポイントを順次呼び出します。

以下のNCCOの例は、異なるタイプの接続の設定方法を示している。

[
  {
    "action": "talk",
    "text": "Please wait while we connect you"
  },
  {
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "timeout": "45",
    "from": "447700900000",
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001",
        "dtmfAnswer": "2p02p"
      }
    ]
  }
]

以下のオプションを使って connect アクションだ:

オプション 説明 必須
endpoint 配列 endpoint オブジェクトに接続する。現在サポートしているのは 最大 一人の endpoint オブジェクトがある。 利用可能なエンドポイント・タイプ. はい
from のNumbers。 E.164 形式で発信者を識別します。実際の電話に接続する場合は、Vonageバーチャル番号のいずれかである必要があります。 いいえ
randomFromNumber に設定する。 true としてランダムな電話番号を使用する。 from.番号は、現在のアプリケーションに割り当てられている番号のリストから選択されます。アプリケーションは、宛先と同じ国の番号を使用しようとします(利用可能な場合)。 randomFromNumber: true との併用はできない。 from.デフォルト値は false. いいえ
eventType に設定する。 synchronous に:
  • を作る。 connect アクション同期
  • イネーブル eventUrl を使用して、呼が特定の状態に移行したときに、現在のNCCOをオーバーライドするNCCOを返す。
いいえ
timeout 電話に出ない場合、Vonageが呼び出し音を止めるまでの秒数を設定します。 endpoint.の間の整数でなければならない。 1 そして 120.デフォルト値は 60. いいえ
limit 通話の最大長(秒)。デフォルトの最大値は 7200 秒(2時間)。 いいえ
machineDetection 宛先が留守番電話であることをVonageが検出した場合の動作を設定します。どちらかに設定します:
  • continue - VonageはHTTPリクエストを event_url コールイベント machine
  • hangup - 通話を終了する
いいえ
advancedMachineDetection Vonageの高度な機械検出の動作を設定します。オーバーライド machineDetection の両方が設定されている場合。以下を参照のこと。 APIリファレンス をご覧ください。この機能は有料です。 Voice API価格 ページの「プログラマブル機能」の下にある。 いいえ
eventUrl Vonageが非同期で呼び出すWebhookエンドポイントを設定します。 コール・ステート.もし eventType に設定されている。 synchronous その eventUrl は、タイムアウトが発生したときに、現在のNCCOを上書きするNCCOを返すことができる。 いいえ
eventMethod へのリクエストにVonageが使用するHTTPメソッド。 イベントURL.デフォルト値は POST. いいえ
ringbackTone を指すURL値。 ringbackTone にリピート再生される。 呼び出し側静寂は聞こえない。その ringbackTone は、通話が完全に接続されると自動的に再生を停止します。電話のエンドポイントに接続する場合、このパラメータを使用することはお勧めしません。 ringbackTone.例 "ringbackTone": "http://example.com/ringbackTone.wav". いいえ

エンドポイントのタイプと値

電話 (PSTN) - E.164形式の電話番号

価値 説明
type エンドポイントのタイプ: phone PSTNエンドポイントの場合。
number で接続する電話番号。 E.164 という形式をとっている。
dtmfAnswer コールに応答すると同時にユーザーに送信される数字を設定します。その * そして # 桁の数字が尊重されます。ポーズは p.各休止は500ミリ秒。
onAnswer 必須 url キー。URLは、その通話が既存の会話に加わる前に、接続先の番号で実行するNCCOを提供する。オプションで ringbackTone キーを指すURL値を指定することができる。 ringbackTone にリピート再生される。 呼び出し側だから、彼らは沈黙だけを聞くことはない。その ringbackTone は、通話が完全に接続されると自動的に再生を停止します。例 {"url":"https://example.com/answer", "ringbackTone":"http://example.com/ringbackTone.wav" }.キー ringback はまだサポートされている。
shaken Vonageをご利用のお客様で、FCCにより米国への通話に署名することが義務付けられている場合、お客様の署名を使ってVoice APIコールをかけるオプションを提供しています。

この機能はリクエスト制です。無効な署名を含む通話は拒否されます。詳しくはお問い合わせください。

このオプションを使用する場合、Vonageがこの呼に使用する必要があるSTIR/SHAKEN Identity Headerコンテンツを配置する必要がある。予想される形式は以下のとおり:
  • ヘッダー、ペイロード、署名を持つJWT
  • アン info パラメータに証明書へのリンクを指定する。
  • アン alg (アルゴリズム)パラメータ。
  • a ppt (パスポートタイプ) パラメータでなければならない。 shaken
表の下に記載されている例を参照のこと。

shaken オプションがある:

eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0LmV4YW1wbGUuY29tL3Bhc3Nwb3J0LnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxMjEyNTU1MTIxMiJdfSwiaWF0IjoxNjk0ODcwNDAwLCJvcmlnIjp7InRuIjoiMTQxNTU1NTEyMzQifSwib3JpZ2lkIjoiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIn0.MEUCIQCrfKeMtvn9I6zXjE2VfGEcdjC2sm5M6cPqBvFyV9XkpQIgLxlvLNmC8DJEKexXZqTZ;info=<https://stir-provider.example.net/cert.cer>;alg=ES256;ppt="shaken"

Applications - 通話をRTC対応アプリケーションに接続します。

価値 説明
type エンドポイントのタイプ: app に対して アプリケーション.
user 接続するユーザーのユーザー名。このユーザー名は ユーザーとして追加.

WebSocket - 接続先の WebSocket。

価値 説明
type エンドポイントのタイプ: websocket WebSocketの場合。
uri ストリーミング先のウェブソケットのURI。
content-type ストリーミングするオーディオのインターネットメディアタイプ。指定可能な値は以下の通り: audio/l16;rate=16000 または audio/l16;rate=8000.
headers 任意のメタデータを含むJSONオブジェクト。参照 ウェブソケットへの接続 例えばヘッダー。
authorization を定義するオプション設定。 Authorization HTTPヘッダーは、WebSocketのオープニング・ハンドシェイクで設定されます。使用方法 type: "vonage" で署名されたウェブフックと同じ JWT を Voice API に含めるようにします。 Authorization ヘッダー (Bearer <JWT>).使用方法 type: "custom" を送信します。 Authorization ヘッダーの値をそのまま使用する。を使用する場合 type: "custom"を提供しなければならない。 value インクルードする生のヘッダ値を含む (例、 Bearer eyJhbGciOi... または ApiKey X9Z...).使用時 type: "vonage", value は無視される。もっと読む これ.

SIP - 接続先のSIPエンドポイント。

価値 説明
type エンドポイントのタイプ: sip SIP用。
uri 接続先のエンドポイントへのSIP URI。 sip:rebekka@sip.example.com.使用方法 TLSおよび/またはSRTPそれぞれを含む。 transport=tls または media=srtp をURLのセミコロン ; を区切り文字として使用する: sip:rebekka@sip.example.com;transport=tls;media=srtp.この特性は user そして domain.
user について user URIのコンポーネントである。これは domain プロパティを使用して、完全なSIP URIを作成します。このプロパティを設定する場合は domain そして去る uri アンセット。
domain ダッシュボードを使用して作成されたトランクの識別子。これは SIPトランキングダッシュボード または プログラマブルSIP API.トランクにプロビジョニングされたURIは user プロパティを使用して、完全なSIP URIを作成します。 したがって、例えば、トランクのURIが sip.example.com そして userexample_userVonageはコールを example_user@sip.example.com.このプロパティを設定する場合は uri をアンセットする。このプロパティは、ドメインURIではなくドメイン名を参照することに注意してください。
headers key => value 必要なメタデータを含む文字列ペア。 { "location": "New York City", "occupation": "developer" }.ヘッダーは以下のようにSIP INVITEの一部として送信される。 X-key: value ヘッダーを送信します。つまり、この例ではこれらのヘッダーが送信される: X-location: New York City そして X-occupation: developer.
standardHeaders 1つのキーを含むJSONオブジェクト User-to-User.これは、ベンダーがサポートしている場合、ユーザー間の情報を送信するために使用されます。 RFC7433.とは違う。 headersの前にキーが付くことはない。 X-標準化されているからだ。例えば { "User-to-User": "342342ef34;encoding=hex" }.Vonageは、User-to-Userヘッダーが有効な文字を使用していることと、コンテンツが許可された最大文字数(256文字)以内であることを確認する以外には、コンテンツを検証しない。

アプリケーションがSIPカスタムヘッダを受信して処理する方法を理解するには、以下のページを参照してください。 プログラマブルSIP.アプリケーションがSIPヘッダを送信する方法を知りたい場合は、次のページを参照してください。 Voice API Webhooks リファレンスガイド.

VBC - Vonage Business Cloud (VBC)エクステンションで、次のような接続が可能です。

価値 説明
type エンドポイントのタイプ: vbc VBCエクステンションのために。
extension 通話を接続するVBC内線番号。

トーク

について talk アクションは合成された音声を会話に送ります。

talkアクションで提供されるテキストは、プレーンなものでも、次のようにしてフォーマットされたものでもかまいません。 エスエスエムエル.SSMLタグは、ピッチや発音を設定したり、複数の言語のテキストを組み合わせることを可能にする音声合成シンセサイザーへのさらなる指示を提供します。SSMLタグはXMLベースで、JSON文字列のインラインで送信されます。

デフォルトでは、トークアクションは同期である。しかし バージン への 真の を設定する必要があります。 入力 アクションは NCCO スタックの後のほうにあります。 以下の NCCO の例では、会話または通話に合成音声メッセージを送信する方法を示します:

[
  {
    "action": "talk",
    "text": "You are listening to a Call made with Voice API"
  }
]

以下のオプションを使って トーク アクションだ:

オプション 説明 必須
text 最大1,500文字の文字列(SSMLタグを除く)。通話または会話で合成されるメッセージを含む。カンマ1つで text は合成音声に短いポーズを追加します。長いポーズを追加するには break タグを使う必要があります。使用するには エスエスエムエル タグでテキストを囲む必要があります。 speak 要素である。 はい
bargeIn に設定する。 true このため、ユーザーがDTMFまたはASR音声入力でアプリケーションと対話すると、このアクションは終了します。この機能を使用すると、ユーザはメッセージ全体を聞くことなくオプションを選択できます。 インタラクティブ・ボイス・レスポンス(IVR).もし bargeIn への true NCCOスタックの次のノントークアクション マスト である input アクションを指定します。デフォルト値は false.

一度 bargeIn に設定されている。 true そのまま true (たとえ bargeIn: false がセットされるまで)。 input アクションに遭遇
いいえ
loop 回数 text が繰り返される。デフォルト値は1。0に設定すると無限にループする。 いいえ
level スピーチが再生される音量レベル。この値は -1 への 10 がデフォルトである。 いいえ
language 言語(BCP-47 書式) を使用します。デフォルトは en-US.可能な値は 音声合成ガイド. いいえ
style ボーカルスタイル(声域、テッシトゥーラ、音色)。デフォルト: 0.可能な値は 音声合成ガイド. いいえ
premium に設定する。 true を指定すると、指定したスタイルのプレミアム版があればそれを使用し、なければ標準版を使用します。デフォルト値は false.プレミアム・ボイスの詳細については、以下をご覧ください。 音声合成ガイド. いいえ

トーク・リターン・パラメータ

参照 Webhookリファレンス に返されるパラメータは eventUrl.

ストリーム

について stream アクションを使うと、オーディオストリームをConversation

デフォルトでは、ストリーム・アクションは同期である。しかし バージン への 真の を設定する必要があります。 入力 アクションはNCCOスタックの後半にある。

以下のNCCOの例は、会話または通話にオーディオストリームを送信する方法を示している:

[
  {
    "action": "stream",
    "streamUrl": ["https://acme.com/streams/music.mp3"]
  }
]

以下のオプションを使って ストリーム アクションだ:

オプション 説明 必須
streamUrl コールまたは会話にストリーミングするmp3またはwav (16ビット)オーディオファイルのURLを1つ含む配列。 はい
level ストリームのオーディオレベルを、-1 >=level<=1 の範囲で、0.1 の精度で設定する。デフォルト値は 0. いいえ
bargeIn に設定する。 true このため、ユーザーがDTMFまたはASR音声入力でアプリケーションと対話すると、このアクションは終了します。この機能を使用すると、ユーザはメッセージ全体を聞くことなくオプションを選択できます。 インタラクティブ・ボイス・レスポンス(IVR ).もし bargeIn への true NCCOスタックの次の非ストリーム・アクションに、さらにもう1つストリーム・アクションを追加する。 マスト である input アクションを指定します。デフォルト値は false.

一度 bargeIn に設定されている。 true そのまま true (たとえ bargeIn: false がセットされるまで)。 input アクションが発生する。
いいえ
loop 回数 audio は、Callがクローズされる前に繰り返される。デフォルト値は 1.に設定する。 0 を無限にループさせる。 いいえ

参照するオーディオ・ストリームはMP3またはWAV形式のファイルでなければなりません。ファイルの再生に問題がある場合は、以下の技術仕様にエンコードしてください: どのような録音済み音声ファイルを使用できますか?

同じオーディオファイルを何度も再生する場合、例えば、同じ録音を何度も通話で使用する場合、次のようなオプションを追加することを検討してください。 キャッシュ制御 ヘッダーを適切な値でURLレスポンスに追加する。

Cache-Control: public, max-age=360000

これにより、Vonageはオーディオファイルを毎回ダウンロードする代わりにキャッシュし、パフォーマンスとユーザー体験を大幅に向上させることができます。キャッシュはHTTPおよびHTTPS URLの両方でサポートされています。

ストリーム・リターン・パラメーター

参照 Webhookリファレンス に返されるパラメータは eventUrl.

インプット

を使用することができます。 input アクションを使用して、通話相手の数字または音声入力を収集します。このアクションは同期的で、Vonageは入力を処理し、それを パラメーター に送られる。 eventUrl リクエストで設定した Webhook エンドポイントを返します。Webhook エンドポイントは、既存の NCCO を置き換える別の NCCO を返し、ユーザー入力に基づいて呼び出しを制御する必要があります。この機能を使用して、対話型音声応答(IVR)を作成できます。たとえば、ユーザが 4 を返す。 コネクト 御社の営業部門に電話を転送するNCCO。

次の NCCO の例は、IVR エンドポイントを設定する方法を示しています:

[
  {
    "action": "talk",
    "text": "Please enter a digit or say something"
  },
  {
    "action": "input",
    "eventUrl": [
      "https://example.com/ivr"
    ],
    "type": [ "dtmf", "speech" ],
    "dtmf": {
      "maxDigits": 1
    },
    "speech": {
      "context": [ "sales", "support" ]
    }
  }
]

以下のNCCOの例では bargeIn を中断できるようにする。 talk アクションを実行します。なお input アクション マスト を持つすべてのアクションに従う。 bargeIn プロパティ(例 talk または stream).

[
  {
    "action": "talk",
    "text": "Please enter a digit or say something",
    "bargeIn": true
  },
  {
    "action": "input",
    "eventUrl": [
      "https://example.com/ivr"
    ],
    "type": [ "dtmf", "speech" ],	
    "dtmf": {
      "maxDigits": 1
    },
    "speech": {
      "context": [ "sales", "support" ]
    }	
  }
]

以下のオプションは input アクションだ:

オプション 説明 必須
type 使用可能な入力タイプ。 [ "dtmf" ] DTMF入力専用、 [ "speech" ] ASRのみ [ "dtmf", "speech" ] どちらもだ。 はい
dtmf DTMFの設定. いいえ
speech 音声認識設定. いいえ
mode 入力処理モード。現在はDTMFにのみ適用可能。有効な値は synchronous (デフォルト)と asynchronous.に設定されている場合 asynchronousすべて DTMFの設定 は空白のままにしてください。非同期モードでは、桁はリアルタイムでイベントウェブフックに1つずつ送信されます。デフォルトの synchronous モードでは、代わりにDTMF設定で制御され、入力は一括して送信される。 いいえ
eventUrl Vonageは、着信側が押した数字をこのURLに送信します。 timeOut 活動休止時または # がDTMFのために押された後、または2) ユーザーが話すのを止めた後、または 30 秒の音声入力。 いいえ
eventMethod イベント情報を event_url デフォルト値は POST. いいえ

DTMF入力設定

注: これらの設定は mode に設定されている。 asynchronous.

オプション 説明 必須
timeOut 着呼側の活動結果は、次のように送られる。 eventUrl ウェブフックエンドポイント timeOut 秒後。デフォルト値は 3.最大は10だ。 いいえ
maxDigits ユーザーが押せる Numbers の桁数。最大値は 20デフォルトは 4 桁である。 いいえ
submitOnHash に設定する。 true でウェブフックエンドポイントに送信されます。 eventUrl を押した後 #.もし # が押されなかった場合、結果は timeOut 秒。デフォルト値は false.つまり、結果は以下の後にウェブフックのエンドポイントに送信されます。 timeOut 秒。 いいえ

音声認識設定

オプション 説明 必須
uuid ユーザーが音声をキャプチャする通話レグの一意のIDで、単一の要素を持つ配列として定義されます。デフォルトでは、通話の最初の結合レグ。 いいえ
endOnSilence ユーザーが話すのを止めてから、入力が完了したと判断するまでの待ち時間を制御します。デフォルト値は 2.0 (秒)。設定可能な値の範囲は 0.4 秒と 10.0 秒。 いいえ
language 利用者が話す予定の言語。フォーマット:BCP-47。デフォルト: en-US. 対応言語一覧. いいえ
context ユーザーから特定の単語が予想される場合に、認識品質を向上させるためのヒント(文字列)の配列。 いいえ
startTimeout ユーザーが話し始めるまでの待機時間を制御します。設定可能な値の範囲は1秒から60秒です。デフォルト値は 10. いいえ
maxDuration 最大発話時間(ユーザーが話し始めてから)を制御します。デフォルト値は60(秒)です。設定可能な値の範囲は1~60秒です。 いいえ
saveAudio に設定する。 true で、音声入力録音(recording_urlにあるウェブフック・エンドポイントに送信されます。 eventUrl.デフォルト値は false. いいえ
sensitivity ノイズと音声を区別するための音声感度。10が低感度、100が最大感度を表す整数値。デフォルトは90。 いいえ

以下の例では eventUrl DTMF入力用のウェブフック:

{
  "speech": { "results": [ ] },
  "dtmf": {
    "digits": "1234",
    "timed_out": true
  },
  "from": "15551234567",
  "to": "15557654321",
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "bbbbbbbb-cccc-dddd-eeee-0123456789ab",
  "timestamp": "2020-01-01T14:00:00.000Z"
}

次の例では、以下のようなパラメータが返される。 eventUrl 音声入力用のウェブフック:

{
  "speech": {
    "recording_url": "https://api-us.nexmo.com/v1/files/eeeeeee-ffff-0123-4567-0123456789ab",
    "timeout_reason": "end_on_silence_timeout",
    "results": [
      {
        "confidence": "0.9405097",
        "text": "sales"
      },
      {
        "confidence": "0.70543784",
        "text": "sails"
      },
      {
        "confidence": "0.5949854",
        "text": "sale"
      }
    ]
  },
  "dtmf": {
    "digits": null,
    "timed_out": false
  },
  "from": "15551234567",
  "to": "15557654321",  
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "bbbbbbbb-cccc-dddd-eeee-0123456789ab",
  "timestamp": "2020-01-01T14:00:00.000Z"
}

インプット・リターン・パラメーター

参照 Webhookリファレンス に返される入力パラメータに使用される。 eventUrl.

通知

を使用する。 notify アクションを使用して、カスタムペイロードをイベントURLに送信します。あなたのウェブフックエンドポイントは、既存のNCCOを置き換える別のNCCOを返すか、既存のNCCOが実行され続けることを意味する空のペイロードを返すことができます。

[
  {
    "action": "notify",
    "payload": {
      "foo": "bar"
    },
    "eventUrl": [
      "https://example.com/webhooks/event"
    ],
    "eventMethod": "POST"
  }
]
オプション 説明 必須
payload イベントURLに送信するJSONボディ。 はい
eventUrl イベントを送信するURL。通知を受け取ったときにNCCOを返すと、それは現在のNCCOを置き換えます。 はい
eventMethod を送信するときに使用する HTTP メソッド。 payload あなたの eventUrl. いいえ

プロンプト音声設定

オプション 説明 必須
language 言語(BCP-47 フォーマット) でプロンプトを表示する。デフォルトは en-US.可能な値は 音声合成ガイド. いいえ
style ボーカルスタイル(声域、テッシトゥーラ、音色)。デフォルト: 0.可能な値は 音声合成ガイド. いいえ

待つ

を使用することができます。 wait アクションを実行すると、待ち時間が追加され、実行中のNCCOの実行が指定した秒数だけ一時停止される。

アクションは同期的である。待ち時間は、NCCO 内で待ちアクションが実行された時点で開始し、指定されたタイムアウト値またはデフォルトのタイムアウト値が経過した時点で終了する。この時点でNCCOは実行を再開する。 この時点で NCCO は実行を再開する。 timeout パラメータは float である。有効な値の範囲は0.1秒から7200秒。0.1未満の値のデフォルトは0.1秒で、7200以上の値のデフォルトは7200秒である。指定しない場合、デフォルトは10秒である。

待機アクションの終了を知らせるコールバックが必要な場合は、待機アクションの後にnotifyアクションを追加してください。

次のNCCOの例は、待機アクションの実行方法を示している:

[
  {
    "action": "talk",
    "text": "Welcome to a Vonage moderated conference"
  },
  {
    "action": "wait",
    "timeout": 0.5
  },
  {
    "action": "talk",
    "text": "We will connect you when an agent is available"
  }
]

以下のオプションを使って wait アクションだ:

オプション 説明 必須
timeout NCCO の次のアクションを実行するまでの待ち時間を制御する。このパラメータは浮動小数点数である。有効な値の範囲は 0.1 秒から 7200 秒である。0.1未満の値のデフォルトは0.1秒で、7200以上の値のデフォルトは7200秒である。デフォルト値は 10. いいえ

譲渡

について transfer アクションは同期である。これを使用して、現在の会話から別の既存の会話にコールレッグを移動できる。この transfer アクションは現在の会話に対して終了し、ターゲットの会話のNCCOはターゲットの 会話の動作を制御し続ける。現在の会話の全てのレッグは、オーディオ設定(canHear, canSpeak, mute)が用意されている場合。

次のNCCOの例は、移籍アクションの実行方法を示している:

[
   ...
   {
     "action": "transfer",
     "conversationId": "CON-f972836a-550f-45fa-956c-12a2ab5b7d22",
     "canHear": [ "9c132730-8c22-4760-a4dc-40502f05b444" ]
   }
   ...
]

以下のオプションを使用して、移籍アクションを制御することができます:

オプション 説明 必須
conversation_id 文字列として定義されるターゲット会話ID。 はい
canHear この参加者が聞くことができる足のUUIDのリストで、文字列の配列として定義されます。提供されない場合、参加者は全員の声を聞くことができます。空のリストが提供された場合、参加者は他の参加者の声を聞くことができません。 いいえ
canSpeak 文字列の配列として定義されます。提供されない場合、参加者は誰からも聞くことができます。空のリストが提供された場合、参加者は誰からも聞こえません。 いいえ
mute 参加者をミュートするにはtrueを設定します。参加者の音声は会話に再生されず、録音されません。を使用する場合 canSpeakその mute パラメータはサポートされていない。 いいえ