WebSockets dans l'API Voice de Vonage

Ce guide explique comment les WebSockets s'intègrent à l'API Voice de Vonage et vous aident à créer des applications sophistiquées en temps réel, telles que des bots vocaux alimentés par l'IA ou des services de transcription en direct.

Qu'est-ce que les WebSockets ?

Les WebSockets sont un protocole de communication qui fournit un moyen d'accès à l'Internet. connexion persistante en duplex intégral entre une application et la plateforme Vonage Voice.
Contrairement au protocole HTTP, qui nécessite une demande distincte pour chaque échange, une WebSocket maintient une seule connexion ouverte sur laquelle les messages peuvent être envoyés dans les deux sens à tout moment.

C'est la solution idéale pour les scénarios nécessitant données en continu à faible latenceIl peut s'agir par exemple d'envoyer et de recevoir des paquets audio en temps réel.

Pourquoi les WebSockets sont-ils importants pour les connecteurs d'IA ?

Dans les applications vocales d'IA, il faut souvent :

Recevoir de l'audio en direct d'un appelant.
Transcrire que l'audio en direct.
Envoyer des réponses audio synthétisées à l'appelant.
Envoyer des métadonnées pour la session.
Signaux de contrôle des échanges de manière dynamique.

Les WebSockets permettent de le faire :

Streaming audio sous forme de paquets binaires.
Échange de messages textuels sous forme de commandes de contrôle ou d'événements.
Envoi de métadonnées au début de la session.
Permettre une interaction quasi-instantanée avec des services d'IA, tels que la reconnaissance vocale, la NLU ou les moteurs TTS.

Mise en place d'un serveur WebSocket dans votre application

Pour connecter Vonage à votre serveur WebSocket (votre application), vous devez :

Déployer un point de terminaison WebSocket accessible via une URL sécurisée (wss://).
Traiter les connexions entrantes initiées par Vonage.
Traiter à la fois messages binaires (audio) et messages textuels (commandes/événements JSON).
Mettre en œuvre, le cas échéant, une logique d'authentification ou d'autorisation.

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

Utilisation d'un NCCO pour établir la connexion WebSocket

Pour demander à Vonage de diffuser de l'audio sur votre serveur WebSocket, configurez un fichier de type NCCO (Nexmo Call Control Object) action de type connect:

Exemple NCCO :

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

Format audio :

Vous contrôlez le format audio via content-type:
- audio/l16;rate=24000: PCM linéaire 16 bits, 24 kHz
- audio/l16;rate=16000: PCM linéaire 16 bits, 16 kHz (recommandé pour la reconnaissance vocale).
- audio/l16;rate=8000: 8kHz si nécessaire.

Authentification de la connexion WebSocket

Lorsque Vonage se connecte à votre serveur WebSocket, vous pouvez vouloir vérifier que la connexion entrante provient bien de Vonage. Vous pouvez le faire en configurant un authorization sur le point de terminaison WebSocket.

Deux modes d'autorisation sont pris en charge :

vonage: Vonage inclut un Authorization dans la poignée de main d'ouverture de WebSocket en utilisant le même format JWT que celui utilisé pour les webhooks signés (Bearer <JWT>). Votre serveur doit valider ce JWT. Voir Crochets web signés pour savoir comment valider les JWT de Vonage.
custom: Votre application fournit un Authorization que Vonage enverra mot pour mot dans la poignée de main d'ouverture. Cela vous permet d'utiliser votre propre schéma d'autorisation et vos propres informations d'identification.

Remarque : Si authorization est omis, il est fixé à nullou à un objet vide ({}), Vonage n'appliquera aucun comportement d'autorisation pour la poignée de main WebSocket.

Voir les détails dans le Référence NCCO.

Interaction bidirectionnelle : Messages audio et textuels

De Vonage à votre application :

Messages binaires : Morceaux audio capturés par l'appelant.
Messages textuels : Événements JSON (par exemple, ouverture d'une connexion, suppression d'une connexion, notifications).

De votre application à Vonage :

Messages binaires : Audio à diffuser à l'appelant.
Messages textuels : Commandes permettant de contrôler la lecture ou de demander des notifications.

Ce flux bidirectionnel permet :

Transcription en temps réel.
Lecture de la parole synthétisée.
Contrôle des tampons de lecture.
Interactions basées sur des événements.

Analyse des paquets Vonage (Binaire vs JSON)

Lorsque votre serveur WebSocket reçoit un message :

Si le message est un Buffer ou un ArrayBuffer :
- C'est données audio (PCM brut).
Si le message est une chaîne de caractères :
- Il s'agit d'un Message de contrôle formaté en JSON.

Exemple d'événement JSON :

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

Inspectez toujours le type de message afin d'acheminer correctement la logique de traitement.

Traitement des paquets audio binaires entrants

Les messages binaires contiennent des données audio PCM brutes capturées par l'appelant.

Caractéristiques principales :

PCM 16 bits signé little-endian.
Fréquence d'échantillonnage définie par content-type (par exemple, 16 000 Hz).
Chaque paquet représente une courte tranche de son (~20ms).

Traitement typique :

Introduire l'audio dans un moteur de reconnaissance vocale.
Mémoire tampon pour une lecture ultérieure.
Sauvegarde sur disque pour analyse.

Envoi de paquets audio binaires à Vonage

Pour restituer le son à l'appelant :

Encodez votre audio en PCM brut.
Correspondre à la fréquence d'échantillonnage et au format spécifiés dans le NCCO.
Envoyer les données audio sous forme de messages WebSocket binaires.

Important :
Vonage met en mémoire tampon les données audio entrantes pour les lire dans l'ordre. Cela vous permet de mettre les fichiers audio en file d'attente sans interruption, mais nécessite une gestion de la mémoire tampon, expliquée comme suit.

Fonctionnement de la mise en mémoire tampon audio

Lorsque vous envoyez des paquets audio binaires :

Vonage tampons en interne.
La taille de la mémoire tampon de WebSocket est de 3072 paquets, ce qui devrait suffire pour environ 60 secondes d'audio.
La lecture démarre automatiquement.
Les paquets suivants sont mis en file d'attente.
Il n'est pas possible d'interrompre la lecture à mi-tampon sans commande de contrôle.

Cette conception garantit une lecture cohérente sans interruption du son.

Effacement de la mémoire tampon audio (`clear` Commandement)

Vers arrêter immédiatement la lecture de l'audio en mémoire tampon, envoyer le clear commande.

Commande de sortie (à partir de votre application) :

{
  "action": "clear"
}

` Effet :

Toutes les données audio en file d'attente sont rejetées.
La lecture s'arrête immédiatement.

Accusé de réception (de la plateforme Vonage) :

{
  "event": "websocket:cleared"
}

Scénario d'utilisation :
Vous devez interrompre la lecture pour répondre de manière dynamique à l'appelant (par exemple, après la détection d'une intrusion).

Notification de la fin de l'audio (`notify` Commandement)

Pour être informé de la fin de la lecture de la mémoire tampon audio en cours, utilisez la fonction notify commande.

Commande de sortie (envoyé après une charge utile audio dont on veut savoir si la lecture est terminée):

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

Comportement :

Si l'audio est en cours de lecture, Vonage envoie une notification entrante à votre application après la fin de la lecture.
Si aucun son n'est diffusé, la notification entrante est renvoyée à votre application immédiatement.

Notification entrante :

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

Scénario d'utilisation :
Synchronisez la logique de votre application (par exemple, démarrez l'enregistrement ou lisez une nouvelle invite après la fin de la précédente).

Écouter un participant spécifique dans une conversation multipartite

Lorsque votre application participe à une conversation avec plusieurs segments d'appel - comme un client et un agent - vous pouvez vouloir que votre connexion WebSocket soit ne recevoir que le son d'un participant spécifique plutôt que l'ensemble de l'audio mixé.

C'est ce qu'on appelle contrôle audio sélectifet elle est obtenue en utilisant le canHear et canSpeak propriétés du NCCO conversation action.

Pourquoi l'utiliser ?

Analyse de la parole : Ne saisissez que ce que dit le client, sans tenir compte de l'agent.
Transcription en temps réel : Enregistrer le côté client pour assurer la conformité.
Chuchotements : Envoyer le son uniquement à l'agent sans que le client ne l'entende.

Comment configurer l'écoute sélective

Pour mettre en place ce système :

Créer une conversation nommée (par exemple, "customer_support").
Connecter les jambes d'appel du client et de l'agent à la conversation.
Ajoutez votre connexion WebSocket à la même conversationprécisant canHear et canSpeak si nécessaire.

Exemple : WebSocket à l'écoute du client uniquement

Voici un exemple de NCCO où :

Le client est associé à la conversation.
L'agent est associé à la conversation.
Le WebSocket se connecte mais ne reçoit que l'audio du client.

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

Comment cela fonctionne-t-il ?

Le WebSocket n'entend que les customer participant.
Il ne renvoie aucun son dans la conversation (canSpeak est vide).
Si vous souhaitez injecter du son (par exemple, des invites AI) et le diffuser uniquement à un participant désigné, vous pouvez inclure l'identifiant de l'appel du participant (jambe) dans canSpeak.
Si vous souhaitez qu'il injecte du son (par exemple, des invites AI) et le diffuse à tous les participants, vous ne devez pas inclure les éléments suivants canSpeak paramètre.

Gestion des déconnexions WebSocket et des options de repli

Lorsque vous utilisez les WebSockets avec l'API Voice de Vonage, vous ne vous fiez pas uniquement à la WebSocket elle-même pour savoir ce qui se passe.
Vonage envoie également rappels d'événements à votre eventUrl webhook. Ces requêtes HTTP POST fournissent des informations fiables sur l'état de l'appel et permettent un comportement de repli en cas d'échec de la connexion WebSocket.

Ceci est important car le simple fait d'observer la fermeture de la WebSocket ne vous permet pas de savoir si la WebSocket se ferme. pourquoi il s'est fermé. Vous avez besoin du webhook d'événement pour déterminer si la déconnexion était intentionnelle ou causée par une erreur.

En quoi cela est-il important ?

Lors de la création d'expériences vocales de production, en particulier celles alimentées par l'IA ou en temps réel, les connexions peuvent être interrompues de manière imprévisible (par exemple, pannes de serveur, délais d'attente du réseau).
Pour offrir une expérience gracieuse à l'appelant, vous pouvez mettre en œuvre la méthode suivante stratégies de repli comme la diffusion d'un message-guide, le transfert vers un agent humain ou la fin polie de l'appel.

Les événements Webhook vous offrent un mécanisme fiable pour détecter ces situations et agir en conséquence.

Comment Vonage vous informe des événements WebSocket

Chaque fois qu'il y a un changement important dans l'état de la connexion WebSocket, Vonage envoie un webhook d'événement à votre site Web. eventUrl.

Exemples de statuts pertinents :

unanswered: Vonage n'a pas pu établir la connexion WebSocket.
failed: La tentative de connexion a échoué.
disconnected: La connexion WebSocket a été interrompue après avoir été établie.

Chaque événement comprend

Les uuid, l'identification de l'appel.
Horodatage.
Toute personnalisation headers que vous avez spécifié dans le NCCO connect action.
Champ d'état décrivant ce qui s'est passé.

Exemple de charge utile d'un événement déconnecté

Cet événement est envoyé lorsque la WebSocket est déconnectée après la connexion - que ce soit en raison d'une erreur ou parce que votre application l'a fermée :

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

Comment distinguer les déconnexions intentionnelles des déconnexions involontaires ?

Il est important de comprendre :

Toute déconnexionsi votre application a intentionnellement fermé la WebSocket ou si elle a été abandonnée en raison d'une erreur, soulève un disconnected événement.
Si vous voulez mettre fin intentionnellement la WebSocket sans déclencher de solution de repli, Vonage recommande de terminant le segment d'appel via l'API Voice de Vonage plutôt que de fermer la connexion WebSocket.
- De cette manière, aucun disconnected est envoyé, et vous pouvez compter sur la réception d'un disconnected uniquement en cas de défaillance involontaire.

Gestion des échecs de connexion pendant l'installation

Parfois, la connexion WebSocket ne peuvent pas être établies en premier lieu (par exemple, si votre serveur est hors ligne).
Vous pouvez configurer votre connect action à utiliser traitement synchrone des événements:

Exemple de NCCO avec un type d'événement synchrone :

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