Listen

{
  "verb": "listen",
  "url": "wss://myrecorder.example.com/calls",
  "mixType" : "stereo"
}

パラメータ

actionHookstring必須

listen 操作の終了時に呼び出す Webhook。
送信される情報には音声ストリームの継続時間が含まれ、録音が DTMF キーによって終了した場合は 'digits' プロパティも含まれます。

bidirectionalAudio.enabledbooleanデフォルト: true

true の場合、双方向音声を有効にします。

bidirectionalAudio.sampleRatenumber

WebSocket 経由で Wipple CPaaS に返送する PCM 音声のサンプルレート。

bidirectionalAudio.streamingbooleanデフォルト: false

true の場合、お客様のアプリケーションから Wipple CPaaS (およびリモートの発信者)への音声のストリーミングを有効にします。

disableBidirectionalAudioboolean非推奨

true の場合、双方向音声を無効にします(bidirectionalAudio.enabled to false を設定するのと同じ効果があります)。

finishOnKeystring

いずれかが検出された場合に listen アクションを終了できる数字キーのセット。

maxLengthnumber

受信する音声ストリームの最大長(秒)。この長さに達すると WebSocket 接続は閉じられます。

metadataobject

WebSocket 接続の確立時にリモートサーバーへ送信する JSON ペイロードに追加するユーザーデータ。

mixTypestringデフォルト: mono

"mono" (単一チャネルを送信)、"stereo" (ブリッジされた両方の通話を2チャネルで送信)、または "mixed" (ブリッジされた両方の通話の音声を1つのミックス音声ストリームとして送信)。

passDtmfbooleanデフォルト: false

true の場合、発信者から検出されたすべての DTMF 数字が、JSON 形式のテキストフレームとして WebSocket 経由で渡されます。

playBeepbooleanデフォルト: false

listen 操作の開始時にビープ音を再生するかどうか。

sampleRatenumberデフォルト: 8000

Wipple CPaaS からリモートサーバーへ送信する PCM 音声のサンプルレート。指定可能な値: 8000、16000、24000、48000、または 64000。

timeoutnumber

listen 操作を終了させる無音の秒数。

transcribeobject

ネストされた transcribe Function。

urlstring必須

接続先リモートサーバーの URL。ws または wss の URL である必要があります。

wsAuth.passwordstring

必要に応じて WebSocket 接続で使用する HTTP Basic 認証のパスワード。

wsAuth.usernamestring

必要に応じて WebSocket 接続で使用する HTTP Basic 認証のユーザー名。

音声フォーマット

音声は、sampleRate プロパティで指定したサンプルレートのリニア 16 ビット PCM エンコーディングで WebSocket 経由で送信されます。音声は WebSocket 接続上のバイナリフレームとして送信されます。サーバーから返送される音声も、bidirectionalAudio.sampleRate プロパティで指定したサンプルレートのリニア 16 ビット PCM エンコード音声であることが期待されます。

bidirectionalAudio.streaming プロパティが true に設定されている場合、サーバーから返送される音声は WebSocket 接続上のバイナリフレームとして送信する必要があり、発信者にストリーミングされます。それ以外の場合、返送される音声は base64 エンコードされた音声コンテンツを含む JSON テキストフレームとして送信されることが期待され、バッファリングされた後、全体を受信した時点で発信者に再生されます。

初期メタデータ

WebSocket 接続の確立直後に、1つのテキストフレームが送信されます。このテキストフレームには、通常 HTTP リクエストで送信されるすべての通話属性(callSid など)に加えて、音声のサンプルレートとストリームを示す sampleRate および mixType プロパティを含む JSON 文字列が格納されています。下の表で説明されている metadata プロパティを使用して、このペイロードに追加のメタデータを加えることもできます。メタデータを含む最初のテキストフレームが送信された後、リモート側は音声を含むバイナリフレームのみを受信することを想定してください。

DTMF の受け渡し

passDtmf プロパティを true に設定すると、通話の相手側が入力した DTMF 数字を JSON テキストフレームとして WebSocket サーバーに渡すことができます。各 DTMF 入力は個別に報告され、そのペイロードには入力された DTMF キーと、 RTP タイムスタンプ単位で報告される継続時間が含まれます。送信されるペイロードは次のようになります。

{
  "event": "dtmf",
  "dtmf": "2",
  "duration": "1600"
}

双方向音声

WebSocket 経由で Wipple CPaaS に音声を返送することもできます。この音声が提供された場合、発信者に再生されます。

双方向音声には2つの異なるモードがあります。

非ストリーミング: base64 エンコードした完全な音声ファイルを JSON テキストフレームとして提供します
ストリーミング: L16 PCM の生音声をバイナリフレームとしてストリーミングします

非ストリーミング

相手側の WebSocket サーバーは、WebSocket 接続上で JSON テキストフレームを送信することで双方向音声を提供します。

{
  "type": "playAudio",
  "data": {
    "audioContent": "base64-encoded content..",
    "audioContentType": "raw",
    "sampleRate": "16000"
  }
}

上の例では、生の(ヘッダーなしの)音声が送信されています。音声は 16 ビット PCM エンコードされている必要があり、サンプルレートは 8000、16000、24000、32000、48000、または 64000 khz のいずれかを設定できます。あるいは、type に "wav" (または "wave")を指定して WAVE ファイル形式を提供することもでき、この場合 sampleRate プロパティは不要です。いずれの場合も、ソケット経由で送信する際は音声を base64 エンコードする必要があります。

最初の playAudio の再生が終了する前に複数の playAudio コマンドが送信された場合、それらはキューに入れられ順番に再生されます。同時にキューに入れられる playAudio コマンドは最大 10 個です。

playAudio コマンドの音声の再生が終了すると、playDone の JSON テキストフレームが WebSocket 接続上で送信されます。

{
  "type": "playDone"
}

WebSocket サーバーは killAudio コマンドを送信して、以前の playAudio コマンドで開始された音声の再生を停止することもできます。

{
  "type": "killAudio"
}

最後に、WebSocket 接続側が listen を終了したい場合は、 disconnect コマンドを送信できます。

{
  "type": "disconnect"
}

ストリーミング

双方向音声を有効にするには、以下のように listen Function で streaming プロパティを使用して明示的に有効にする必要があります。

{
  verb: 'listen',
  bidirectionalAudio: {
    enabled: true,
    streaming: true,
    sampleRate: 8000
  }
}

その後、アプリケーションは指定したサンプルレートのリニア 16 ビット PCM 生データのバイナリフレームを WebSocket 接続上で送信します。WebSocket 経由で受信したいサンプルレートと、音声を返送する際のサンプルレートの両方を指定でき、両者は同じである必要はありません。以下の例では、8k サンプリングで受信し、 16K サンプリングで返送するように選択しています。任意の長さのフレームを送信でき、Wipple CPaaS は受信した音声をバッファリングして正しいサンプルレートで再生しますが、固定長のメッセージ(8Khz では 320 バイト、16Khz では 640 バイト)を送信することを推奨します。各サンプルは 16 ビットで 2 バイトを占めるため、最良の再生品質を確保するにはフレームは常に偶数バイトにしてください。

{
  verb: 'listen',
  sampleRate: 8000
  bidirectionalAudio: {
    enabled: true,
    streaming: true,
    sampleRate: 16000
  }
}

コマンド

WebSocket 経由で次のコマンドを JSON フレームとして送信できます。

disconnect
killAudio
mark
clearMarks

disconnect

{
  "type": "disconnect"
}

これにより、Wipple CPaaS 側から WebSocket が閉じられ、関連する listen Function が終了します。

killAudio

{
  "type": "killAudio"
}

これにより、双方向ソケットから再生中の音声と、バッファリングされている音声がすべて破棄されます。

mark

{
  "type": "mark",
  "data": {
    "name": "my-mark-1"
  }
}

お客様側の処理を、提供した音声ストリームの再生と同期させたい場合は、mark コマンドを送信できます。提供した音声は通常ストリーミング前にバッファリングされるため、特定の音声の再生開始または完了のタイミングを知りたい場合は、同期したいストリーム内の位置で name プロパティを付けた mark コマンドを送信してください。再生中にその音声ストリームの位置に到達すると、対応する JSON フレームが WebSocket 経由で返されます。

{
  "type": "mark",
  "data": {
    "name": "my-mark-1",
    "event": "playout"
  }
}

event には、再生中に音声ストリームがマークに到達した場合は playout、 killAudio コマンドによってマークが再生されなかった場合は cleared のいずれかが含まれることに注意してください。

clearMarks

{
  "type": "clearMarks"
}

このコマンドは、追跡中のすべての音声マークをクリア(削除)します。この方法でマークを削除すると、削除されたマークに対する mark イベントは受信されません。