Vonage Voice API の WebSockets

このガイドでは、WebSocketがVonage Voice APIとどのように統合され、AIを搭載した音声ボットやライブ書き起こしサービスなど、高度なリアルタイムアプリケーションの構築に役立つかを説明します。

ウェブソケットとは何か？

WebSocketは、以下のような通信プロトコルを提供する。 持続的な全二重接続 アプリケーションと Vonage Voice プラットフォームの間で使用します。
各交換に個別のリクエストを必要とするHTTPとは異なり、WebSocketは、いつでも双方向にメッセージを送信することができる単一のオープン接続を維持します。

を必要とするシナリオに最適です。 低遅延ストリーミングデータ例えば、オーディオパケットをリアルタイムで送受信する。

なぜAIコネクターにとってWebSocketが重要なのか？

AI音声アプリケーションでは、多くの場合、次のことが必要です：

• ライブ音声の受信 発信者から。
• 書き写す そのライブ・オーディオ。
• 合成されたオーディオ応答を送信 を発信者に返す。
• メタデータを送信する セッションのために。
• 制御信号の交換 ダイナミックに。

ウェブソケットはこれを可能にする：

• オーディオをバイナリパケットとしてストリーミング。
• 制御コマンドまたはイベントとしてテキストメッセージを交換する。
• セッションの最初にメタデータを送信する。
• 音声認識、NLU、TTSエンジンなどのAIサービスとほぼ瞬時に対話できるようにする。

アプリケーションにWebSocketサーバーを設定する

VonageをWebSocketサーバー（アプリケーション）に接続するには、以下の手順が必要です：

1. WebSocketエンドポイントを配置する 安全な(wss://)URLでアクセスできる。
2. Vonageによって開始された着信接続を処理する。
3. 両方を処理する バイナリメッセージ (オーディオ）と テキストメッセージ (JSONコマンド/イベント）。
4. オプションとして、認証または認可ロジックを実装する。

例（Node.js、ws）：

const WebSocket = require('ws');
const server = new WebSocket.Server({ port: 8080 });

server.on('connection', socket => {
  console.log('Vonage connected');
  
  socket.on('message', message => {
    if (typeof message === 'string') {
      // Handle JSON commands or events
      console.log('Text message:', message);
    } else {
      // Handle binary audio
      console.log('Binary audio packet received');
    }
  });
  
  socket.on('close', () => {
    console.log('WebSocket disconnected');
  });
});

NCCOを使ってWebSocket接続を確立する

音声をWebSocketサーバーにストリーミングするようにVonageに指示するには、次のように設定します。 NCCO（ネクスモ・コール・コントロール・オブジェクト） タイプのアクション connect:

NCCOの例：

[
  {
    "action": "connect",
    "endpoint": [
      {
        "type": "websocket",
        "uri": "wss://your-server.example.com",
        "content-type": "audio/l16;rate=16000",
        "headers": {
          "custom-header": "value"
        }
      }
    ]
  }
]

オーディオフォーマット：

• オーディオフォーマットは content-type:
  • audio/l16;rate=24000:16ビットリニアPCM、24kHz
  • audio/l16;rate=16000:16ビットリニアPCM、16kHz（音声認識に推奨）。
  • audio/l16;rate=8000必要であれば、8kHzを使用する。

WebSocket接続の認証

Vonage が WebSocket サーバーに接続する際、着信接続が Vonage からのものであることを確認したい場合があります。これは authorization オブジェクトを WebSocket エンドポイントに置く。

サポートされている認証モードは2つある：

• vonage: Vonageには Authorization ヘッダは、署名付きウェブフックに使われるのと同じJWTフォーマットを使って、ウェブソケット・オープニング・ハンドシェイクで使われる(Bearer <JWT>).サーバーはこのJWTを検証する必要があります。参照 署名入りウェブフック を参照してください。
• custom: アプリケーションは Authorization ヘッダ値は Vonage がオープニングハンドシェイクでそのまま送ります。これにより、独自の認証スキームと認証情報を使用することができます。

詳細は NCCOリファレンス.

双方向のインタラクション：音声メッセージとテキストメッセージ

Vonageからアプリケーションへ：

• バイナリメッセージ： 発信者からキャプチャしたオーディオチャンク。
• テキストメッセージ： JSONイベント（コネクションのオープン、クリア、通知など）。

アプリケーションからVonageへ：

• バイナリメッセージ： 発信者に再生する音声。
• テキストメッセージ： 再生をコントロールしたり、通知を要求するコマンド。

この双方向の流れが可能にする：

• リアルタイム転写。
• 合成音声の再生。
• 再生バッファのコントロール。
• イベント・ドリブン・インタラクション。

Vonageパケットの解析（バイナリ vs JSON）

WebSocketサーバーがメッセージを受信したとき：

• メッセージが Buffer または ArrayBuffer の場合：
  • それは 音声データ (生のPCM）。
• メッセージが文字列の場合：
  • それは JSON形式のコントロール・メッセージ.

JSONイベントの例：

{
    "event":"websocket:connected",
    "content-type":"audio/l16;rate=16000",
    "prop1": "value1",
    "prop2": "value2"
}

処理ロジックを正しくルーティングするために、常にメッセージタイプを検査する。

受信バイナリオーディオパケットの処理

バイナリメッセージには、発呼側からキャプチャされた生のPCMオーディオが含まれる。

主な特徴

• 16ビット符号付きリトルエンディアンPCM。
• で定義されるサンプルレート。 content-type (例えば、16,000Hz）。
• 各パケットはオーディオの短いスライス（~20ms）を表す。

典型的な加工：

• 音声を音声認識エンジンに送り込む。
• 後で再生するためのバッファ。
• 分析のためにディスクに保存する。

Vonageへのバイナリオーディオパケットの送信

通話相手に音声を再生する：

1. オーディオを生のPCMとしてエンコードする。
2. NCCOで指定されたサンプルレートとフォーマットに合わせる。
3. 音声データをバイナリのWebSocketメッセージとして送信する。

重要だ：
Vonageは入力されたオーディオを順番に再生するようにバッファリングします。これにより、オーディオを隙間なくキューに入れることができますが、バッファ管理が必要になります。

オーディオバッファリングの仕組み

バイナリーオーディオパケットを送信する場合：

• ボネージ バッファ 社内で
• WebSocketのバッファサイズは3072パケットで、約60秒のオーディオに十分なはずだ。
• 自動的に再生が始まります。
• それ以降のパケットはキューに入れられる。
• コントロール・コマンドなしで、バッファの途中で再生を中断することはできない。

この設計により、音声のズレのない安定した再生が可能になります。

オーディオバッファのクリアclear コマンド)

へ 直ちに停止する バッファリングされたオーディオを再生するには clear コマンドを使用している。

アウトバウンド・コマンド (アプリケーションから）：

{
  "action": "clear"
}

` 効果

• キューに入れられたオーディオはすべて破棄される。
• 再生は直ちに停止する。

受信確認 (Vonageプラットフォームより）：

{
  "event": "websocket:cleared"
}

使用シナリオ：
通話相手に動的に対応するためには、再生を中断する必要がある（例えば、乱入を検知した後など）。

オーディオ終了の通知 (notify コマンド)

現在のオーディオバッファの再生終了を通知するには notify コマンドを使用している。

アウトバウンド・コマンド (再生が終了したかどうかを知りたいオーディオペイロードの後に送信する):

{
  "action": "notify",
  "payload": {
    "customKey": "customValue"
  }
}

振る舞い：

• オーディオが再生されている場合、Vonageは再生終了後にアプリケーションに受信通知を送信します。
• 音声が再生されていない場合、受信通知はアプリケーションに返送されます。 すぐに.

インバウンドの通知：

{
  "event": "websocket:notify",
  "payload": {
    "customKey": "customValue"
  }
}

使用シナリオ：
アプリケーションロジックを同期させる（例えば、前のプロンプトが終了した後に録画を開始したり、新しいプロンプトを再生したりする）。

多人数会話で特定の相手の話を聞く

アプリケーションが 会話 顧客とエージェントなど、複数のコールレグがある場合、WebSocket接続を次のようにしたい場合があります。 特定の参加者からの音声のみを受信 ミックスされたオーディオ全体ではなく

これをこう呼ぶ。 セレクティブ・オーディオ・コントロールを使用している。 canHear そして canSpeak NCCOの特性 conversation アクションだ。

なぜこれを使うのか？

• 音声分析： エージェントを無視して、顧客の発言だけを捕捉する。
• リアルタイム転写： 顧客側のコンプライアンスを記録する。
• ウィスパーのプロンプト： 顧客に聞こえることなく、音声のみをエージェントに送信します。

選択リスニングの設定方法

これを設定する：

1. 名前付き会話を作成する (例 "customer_support").
2. 顧客とエージェントのコールレッグを会話につなげる.
3. WebSocket接続を同じ会話に追加すると指定する。 canHear そして canSpeak 必要に応じて

例WebSocketが顧客だけをリスンする

以下はNCCOの例である：

• 顧客は会話に加わる。
• エージェントは会話に加わる。
• WebSocketは接続するが、顧客の音声を受信するだけである。

カスタマー・レッグ NCCO

[
  {
    "action": "conversation",
    "name": "support_room"
  }
]

レッグNCCOの代理人：

[
  {
    "action": "conversation",
    "name": "support_room"
  }
]

ウェブソケット・レッグNCCO

[
  {
    "action": "conversation",
    "name": "support_room",
    "canHear": ["6a4d6af0-55a6-4667-be90-8614e4c8e83c"], // Customer leg ID
    "canSpeak": []
  }
]

どのように機能するのか：

• ウェブソケット を聞くだけである。 customer 参加者.
• それは 会話に音声を送り返さない (canSpeak は空）。
• 音声（AIプロンプトなど）を注入し、指定した参加者のみに音声を再生させたい場合は、参加者のコール（レグ）IDを canSpeak.
• 音声（AIプロンプトなど）を注入し、参加者全員に音声を再生させたい場合は、以下を含めない。 canSpeak パラメータが必要だ。

WebSocketの切断とフォールバック・オプションの処理

Vonage Voice APIでWebSocketを使用する場合、何が起こっているかを知るためにWebSocket自体に依存するだけではありません。
Vonageはまた、次のようなサービスも提供している。 イベントコールバック あなたの ウェブフック.これらのHTTP POSTリクエストは、コールステータスに関する信頼できる情報を提供し、WebSocket接続が失敗した場合のフォールバック動作を可能にする。

これは重要なことで、単にWebSocketが閉じるのを観察するだけでは、次のことがわからないからだ。 なぜ 閉じた。切断が意図的なものかエラーによるものかを判断するには、イベント・ウェブフックが必要です。

なぜそれが重要なのか？

本番の音声エクスペリエンス、特にAIを搭載したものやリアルタイムのものを構築する場合、接続が予測不可能に切断されることがある（サーバーのクラッシュやネットワークのタイムアウトなど）。
呼び出し側に優雅な体験を提供するには、次のように実装することができる。 フォールバック戦略 例えば、プロンプトを再生したり、人間のエージェントに転送したり、丁寧に通話を終了したりする。

Webhookイベントは、これらの状況を検出し、それに応じて行動するための信頼性の高いメカニズムを提供します。

VonageがWebSocketイベントを通知する方法

WebSocket接続のステータスに大きな変化があるたびに、VonageはイベントWebhookをお客様の eventUrl.

関連するステータスの例

• unanswered:Vonage は WebSocket 接続を確立できませんでした。
• failed:接続に失敗しました。
• disconnected:WebSocket 接続が確立後に切断されました。

各イベントには以下が含まれる：

• について uuid, 通話を特定する。
• タイムスタンプ。
• カスタム headers NCCOで指定した connect アクションだ。
• 何が起こったかを示すステータスフィールド。

切断イベント・ペイロードの例

このイベントは、WebSocketが接続された後に切断されたときに送信されます（エラーのためであれ、アプリケーションがそれを閉じたためであれ）：

{
  "from": "442079460000",
  "to": "wss://example.com/socket",
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "status": "disconnected",
  "timestamp": "2020-03-31T12:00:00.000Z",
  "headers": {
    "caller-id": "447700900123"
  }
}

意図的な切断と非意図的な切断の見分け方

理解することが重要だ：

• あらゆる切断アプリケーションが意図的にWebSocketを閉じたのか、それともエラーで切断されたのか、 を上げている。 disconnected イベント.
• もしそうしたいなら 意図的終了 フォールバックをトリガーせずにWebSocketを使用する場合、Vonageは以下を推奨します。 Vonage Voice API経由でのコールレッグの終了 単にWebSocket接続を閉じるのではなく。
  • この方法なら disconnected webhookが送信され、その受信に頼ることができます。 disconnected 意図的でない失敗に対してのみ。

セットアップ中の接続失敗の処理

時々、WebSocket接続 そもそも成立しない (サーバーがオフラインの場合など）。
を設定することができます。 connect 使用するアクション 同期イベント処理:

synchronous eventTypeを持つNCCOの例：

[
  {
    "action": "connect",
    "eventType": "synchronous",
    "eventUrl": [
      "https://example.com/events"
    ],
    "from": "447700900000",
    "endpoint": [
      {
        "type": "websocket",
        "uri": "wss://example.com/socket",
        "content-type": "audio/l16;rate=16000",
        "headers": {
          "caller-id": "447700900123"
        }
      }
    ]
  }
]

どのように機能するのか：

• 接続に失敗した場合、Vonageは直ちにイベントをお客様の eventUrl.
• イベント status は unanswered または failed.
• あなたは 新しいNCCOで対応 メッセージの再生や通話のリダイレクトなどのフォールバック動作を記述する。

接続失敗イベント・ペイロードの例

{
  "from": "442079460000",
  "to": "wss://example.com/socket",
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "status": "unanswered",
  "timestamp": "2020-03-31T12:00:00.000Z",
  "headers": {
    "caller-id": "447700900123"
  }
}

フォールバック戦略の導入

ウェブフックに status: disconnected, failedあるいは unansweredあなたはできる：

• 新しいNCCOを返す を webhook レスポンスに追加して、フォールバックを処理します (例: プロンプトを再生する)。
• オリジナルのNCCOを継続させる追加アクションがある場合は
• 通話を終了するそれ以上の処置が指定されない場合。

フォールバックNCCOの例：

[
  {
    "action": "talk",
    "text": "We are unable to connect you at the moment. Please try again later."
  }
]

AIエンジンとの接続

一般的なAIエンジンに接続するためのVonageサンプル・アプリケーションは以下をご覧ください：

• アマゾン・ノヴァ・ソニック音声合成
• カルテシア音声合成
• ディープグラム音声テキスト
• Vonage AI Studio向けDeepgram音声合成テキスト
• ディープグラム音声合成 / OpenAI LLM / イレブンラボ音声合成
• ディープグラム音声エージェント音声合成
• イレブンラボの会話AI
• OpenAIリアルタイムAPI