WebSockets in der Vonage Voice API

In diesem Leitfaden wird erläutert, wie WebSockets in die Voice API von Vonage integriert werden und Ihnen dabei helfen, anspruchsvolle Echtzeit-Applikationen zu erstellen, z. B. KI-gesteuerte Voice Bots oder Live-Transkriptionsdienste.

Was sind WebSockets?

WebSockets sind ein Kommunikationsprotokoll, das eine dauerhafte Vollduplex-Verbindung zwischen einer Anwendung und der Vonage Voice-Plattform.
Im Gegensatz zu HTTP, bei dem für jeden Austausch eine separate Anfrage erforderlich ist, unterhält ein WebSocket eine einzige offene Verbindung, über die jederzeit Nachrichten in beide Richtungen gesendet werden können.

Dies ist ideal für Szenarien, die Folgendes erfordern Streaming-Daten mit niedriger Latenzwie das Senden und Empfangen von Audiopaketen in Echtzeit.

Warum sind WebSockets für AI-Konnektoren wichtig?

Bei KI-Sprachapplikationen müssen Sie das oft tun:

Empfangen Sie Live-Audio von einem Anrufer.
umschreiben. das Live-Audio.
Synthetisierte Audioantworten senden zurück zum Anrufer.
Metadaten senden für die Sitzung.
Austausch von Steuersignalen dynamisch.

WebSockets ermöglichen dies durch:

Audio-Streaming in Form von Binärpaketen.
Austausch von Textnachrichten als Steuerbefehle oder Ereignisse.
Senden von Metadaten zu Beginn der Sitzung.
Ermöglichung einer nahezu sofortigen Interaktion mit KI-Diensten, wie Spracherkennung, NLU oder TTS-Engines.

Einrichten eines WebSocket-Servers in Ihrer Applikation

Um Vonage mit Ihrem WebSocket-Server (Ihrer Anwendung) zu verbinden, müssen Sie:

Bereitstellen eines WebSocket-Endpunkts über eine sichere (wss://) URL zugänglich.
Bearbeiten Sie eingehende Verbindungen, die von Vonage initiiert wurden.
Beides verarbeiten Binärnachrichten (Audio) und Textnachrichten (JSON-Befehle/Ereignisse).
Optional kann eine Authentifizierungs- oder Autorisierungslogik implementiert werden.

Beispiel (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');
  });
});

Verwendung eines NCCO zum Herstellen der WebSocket-Verbindung

Um Vonage anzuweisen, Audio an Ihren WebSocket-Server zu streamen, konfigurieren Sie eine NCCO (Nexmo Call Control Objekt) Aktion vom Typ connect:

Beispiel NCCO:

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

Audio-Format:

Sie steuern das Audioformat über content-type:
- audio/l16;rate=24000: 16-bit linear PCM, 24kHz
- audio/l16;rate=16000: 16-bit linear PCM, 16kHz (empfohlen für Spracherkennung).
- audio/l16;rate=8000: 8kHz, falls erforderlich.

Bidirektionale Interaktion: Audio- und Textnachrichten

Von Vonage zu Ihrer Applikation:

Binäre Nachrichten: Vom Anrufer aufgezeichnete Audiobrocken.
Textnachrichten: JSON-Ereignisse (z. B. Verbindungsaufbau, -abbau, Benachrichtigungen).

Von Ihrer Applikation zu Vonage:

Binäre Nachrichten: Audio, das dem Anrufer vorgespielt wird.
Textnachrichten: Befehle zur Steuerung der Wiedergabe oder zur Anforderung von Benachrichtigungen.

Dieser bidirektionale Fluss ermöglicht:

Transkription in Echtzeit.
Wiedergabe von synthetisierter Sprache.
Kontrolle über Wiedergabepuffer.
Ereignisgesteuerte Interaktionen.

Analysieren von Vonage-Paketen (Binär vs. JSON)

Wenn Ihr WebSocket-Server eine Nachricht empfängt:

Wenn die Nachricht ein Buffer oder ArrayBuffer ist:
- Es ist Audiodaten (rohes PCM).
Wenn die Nachricht eine Zeichenkette ist:
- Es ist ein JSON-formatierte Kontrollnachricht.

Beispiel JSON-Ereignis:

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

Überprüfen Sie immer den Nachrichtentyp, um die Verarbeitungslogik korrekt zu leiten.

Behandlung eingehender binärer Audiopakete

Binäre Nachrichten enthalten rohes PCM-Audio, das vom Anrufer aufgenommen wurde.

Wesentliche Merkmale:

16-Bit signed little-endian PCM.
Abtastrate definiert durch content-type (z. B. 16.000 Hz).
Jedes Paket repräsentiert einen kurzen Abschnitt des Tons (~20ms).

Typische Verarbeitung:

Geben Sie die Audiodaten an eine Spracherkennungsmaschine weiter.
Puffer für die spätere Wiedergabe.
Für die Analyse auf der Festplatte speichern.

Senden von binären Audiopaketen an Vonage

Um dem Anrufer den Ton wiederzugeben:

Kodieren Sie Ihr Audiomaterial als rohes PCM.
Stimmen Sie die im NCCO angegebene Abtastrate und das Format ab.
Senden Sie die Audiodaten als binäre WebSocket-Nachrichten.

Das ist wichtig:
Vonage puffert eingehende Audiosignale, um sie der Reihe nach abzuspielen. Dies ermöglicht eine lückenlose Wiedergabe in der Warteschlange, erfordert jedoch eine Pufferverwaltung, die im Folgenden erläutert wird.

So funktioniert die Audiopufferung

Wenn Sie binäre Audiopakete senden:

Vonage Puffer sie intern.
Die WebSocket-Puffergröße beträgt 3072 Pakete, was für etwa 60 Sekunden Audio ausreichen sollte.
Die Wiedergabe beginnt automatisch.
Nachfolgende Pakete werden in eine Warteschlange gestellt.
Sie können die Wiedergabe in der Mitte des Puffers nicht ohne einen Steuerbefehl unterbrechen.

Dieses Design gewährleistet eine konsistente Wiedergabe ohne Audiolücken.

Löschen des Audiopuffers (`clear` Befehl)

An sofort aufhören Wiedergabe von gepuffertem Audio, senden Sie die clear Befehl.

Ausgehender Befehl (aus Ihrer Bewerbung):

{
  "action": "clear"
}

` Wirkung:

Alle in der Warteschlange stehenden Audiosignale werden verworfen.
Die Wiedergabe wird sofort gestoppt.

Eingehende Quittung (von der Vonage-Plattform):

{
  "event": "websocket:cleared"
}

Verwendungsszenario:
Sie müssen die Wiedergabe unterbrechen, um dynamisch auf den Anrufer reagieren zu können (z. B. nach der Erkennung eines Einbruchs).

Benachrichtigung bei Beendigung des Audios (`notify` Befehl)

Um benachrichtigt zu werden, wenn die Wiedergabe des aktuellen Audiopuffers beendet ist, verwenden Sie die notify Befehl.

Ausgehender Befehl (wird nach einem Audio-Payload gesendet, von dem Sie wissen wollen, ob er zu Ende gespielt wurde):

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

Verhalten:

Wenn Audio wiedergegeben wird, sendet Vonage nach Beendigung der Wiedergabe eine eingehende Benachrichtigung an Ihre Anwendung.
Wenn kein Ton abgespielt wird, wird die eingehende Benachrichtigung an Ihre Anwendung zurückgeschickt. sofort.

Eingehende Benachrichtigung:

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

Verwendungsszenario:
Synchronisieren Sie Ihre Anwendungslogik (z. B. starten Sie die Aufnahme oder spielen Sie einen neuen Prompt ab, nachdem der vorherige beendet wurde).

Zuhören eines bestimmten Teilnehmers in einem Mehrparteiengespräch

Wenn Ihre Anwendung an einer Gespräch mit mehreren Gesprächspartnern - z. B. einem Kunden und einem Agenten - möchten Sie vielleicht, dass Ihre WebSocket-Verbindung nur Audio von einem bestimmten Teilnehmer empfangen und nicht den gesamten gemischten Ton.

Dies wird als selektive Audiosteuerungund wird durch die Verwendung der canHear und canSpeak Eigenschaften des NCCO conversation Aktion.

Warum sollten Sie dies verwenden?

Sprachanalytik: Erfassen Sie nur, was der Kunde sagt, und ignorieren Sie den Agenten.
Transkription in Echtzeit: Aufzeichnung der Kundenseite zur Einhaltung der Vorschriften.
Flüsteraufforderungen: Senden Sie Audio nur an den Agenten, ohne dass der Kunde es hört.

So konfigurieren Sie selektives Mithören

So richten Sie dies ein:

Eine benannte Konversation erstellen (z.B., "customer_support").
Verbinden Sie die Gesprächsabschnitte des Kunden und des Agenten mit dem Gespräch.
Fügen Sie Ihre WebSocket-Verbindung zu derselben Konversation hinzuunter Angabe von canHear und canSpeak nach Bedarf.

Beispiel: WebSocket, der nur den Kunden abhört

Nachfolgend finden Sie ein NCCO-Beispiel:

Der Kunde wird in das Gespräch einbezogen.
Der Agent wird in das Gespräch einbezogen.
Der WebSocket stellt eine Verbindung her, empfängt aber nur den Ton des Kunden.

Kunde Leg NCCO:

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

Agent Leg NCCO:

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

WebSocket Leg NCCO:

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

Wie das funktioniert:

Der WebSocket hört nur die customer Teilnehmer.
Es sendet keinen Ton zurück in das Gespräch (canSpeak leer ist).
Wenn Sie möchten, dass Audio (z. B. AI-Prompts) eingespeist und nur einem bestimmten Teilnehmer vorgespielt wird, können Sie die ID des Teilnehmeranrufs (Bein) in canSpeak.
Wenn Sie möchten, dass Audio (z. B. AI-Prompts) eingespeist und allen Teilnehmern vorgespielt wird, müssen Sie Folgendes nicht angeben canSpeak Parameter.

Handhabung von WebSocket-Verbindungsabbrüchen und Fallback-Optionen

Wenn Sie WebSockets mit der Vonage Voice API verwenden, verlassen Sie sich nicht nur auf den WebSocket selbst, um zu wissen, was passiert.
Vonage sendet auch Ereignisrückrufe zu Ihrem eventUrl webhook. Diese HTTP-POST-Anfragen liefern maßgebliche Informationen über den Anrufstatus und ermöglichen ein Rückfallverhalten, wenn die WebSocket-Verbindung fehlschlägt.

Dies ist wichtig, denn das bloße Beobachten des Schließens des WebSockets sagt Ihnen nichts über die warum sie geschlossen wurde. Sie benötigen den Ereignis-Webhook, um festzustellen, ob die Unterbrechung der Verbindung absichtlich oder durch einen Fehler verursacht wurde.

Warum ist das so wichtig?

Bei der Entwicklung von Spracherlebnissen für die Produktion - insbesondere von KI-gesteuerten oder Echtzeit-Erlebnissen - kann es zu unvorhersehbaren Verbindungsabbrüchen kommen (z. B. Serverabstürze, Netzwerk-Timeouts).
Um dem Anrufer eine angenehme Erfahrung zu bieten, können Sie Folgendes implementieren Ausweichstrategien wie z. B. das Abspielen einer Eingabeaufforderung, das Weiterleiten an einen menschlichen Agenten oder das höfliche Beenden des Anrufs.

Webhook-Ereignisse bieten Ihnen einen zuverlässigen Mechanismus, um diese Situationen zu erkennen und entsprechend zu handeln.

Wie Vonage Sie über WebSocket-Ereignisse benachrichtigt

Bei jeder signifikanten Änderung des WebSocket-Verbindungsstatus sendet Vonage einen Ereignis-Webhook an Ihre eventUrl.

Beispiele für relevante Status:

unanswered: Vonage konnte die WebSocket-Verbindung nicht herstellen.
failed: Der Verbindungsversuch ist fehlgeschlagen.
disconnected: Die WebSocket-Verbindung wurde nach dem Aufbau abgebrochen.

Jede Veranstaltung umfasst:

Die uuid, den Anruf zu identifizieren.
Zeitstempel.
Jede benutzerdefinierte headers die Sie in der NCCO connect Aktion.
Das Statusfeld, das beschreibt, was passiert ist.

Beispiel Ereignis-Payload bei Verbindungsabbruch

Dieses Ereignis wird gesendet, wenn der WebSocket nach der Verbindung getrennt wird - sei es aufgrund eines Fehlers oder weil Ihre Anwendung ihn geschlossen hat:

{
  "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"
  }
}

Wie unterscheidet man zwischen beabsichtigten und unbeabsichtigten Unterbrechungen?

Wichtig zu verstehen:

Jede Unterbrechung der Verbindungob Ihre Anwendung den WebSocket absichtlich geschlossen hat oder ob er aufgrund eines Fehlers gelöscht wurde, erhebt eine disconnected Veranstaltung.
Wenn Sie möchten, dass absichtlich beenden den WebSocket ohne Auslösung eines Fallbacks zu nutzen, empfiehlt Vonage Beenden des Gesprächs über die Vonage Voice API anstatt nur die WebSocket-Verbindung zu schließen.
- Auf diese Weise wird kein disconnected Webhook gesendet wird, und Sie können sich darauf verlassen, dass Sie disconnected nur bei unbeabsichtigten Fehlern.

Behandlung fehlgeschlagener Verbindungen während der Einrichtung

Manchmal ist die WebSocket-Verbindung nicht von vornherein festgelegt werden kann (zum Beispiel, wenn Ihr Server offline ist).
Sie können Ihre connect zu verwendende Aktion synchrone Ereignisbehandlung:

Beispiel NCCO mit synchronem eventType:

[
  {
    "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"
        }
      }
    ]
  }
]

Wie es funktioniert:

Wenn der Verbindungsversuch fehlschlägt, POSTet Vonage sofort ein Ereignis an Ihre eventUrl.
Die Veranstaltung status wird sein unanswered oder failed.
Sie können mit einem neuen NCCO reagieren die das Ausweichverhalten beschreiben, wie z. B. das Abspielen einer Nachricht oder die Weiterleitung des Anrufs.

Beispiel Ereignis-Payload für fehlgeschlagene Verbindungen

{
  "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"
  }
}

Implementierung von Fallback-Strategien

Wenn Sie einen Webhook mit status: disconnected, failed, oder unansweredkönnen Sie:

Rückgabe eines neuen NCCO in Ihrer Webhook-Antwort, um den Fallback zu behandeln (z. B. eine Eingabeaufforderung abspielen).
Erlauben Sie die Fortsetzung des ursprünglichen NCCOwenn es zusätzliche Aktionen gibt.
Beenden Sie den Anrufwenn keine weitere Aktion angegeben wird.

Beispiel Fallback NCCO:

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

Verbindung zu AI-Engines

Nachfolgend finden Sie Beispiel-Applikationen von Vonage für die Anbindung an gängige AI-Engines:

Navigation