Stream audio dans un appel téléphonique avec Node.js

Introduction

Lorsque vous recevez une cliente en appel vocal, vous avez toute son attention. Pourquoi ne pas profiter de cette occasion pour l'informer des dernières nouvelles concernant votre entreprise, lui transmettre un message inspirant de votre PDG ou même lui faire écouter votre dernier jingle publicitaire ?

Dans cet article de blog, vous apprendrez comment jouer un fichier audio dans un appel actif de manière programmatique à l'aide de l Voice API de Vonage de Vonage et Node.js.

Avant de commencer

Pour réaliser cet exemple, vous aurez besoin de Node.js. Si vous ne l'avez pas encore, installez-le à partir du site Web de site web de Node.js.

Vous pouvez fournir un numéro dans le tableau de bord du développeur de Vonage, mais nous allons vous expliquer comment utiliser le CLI de Vonage de Vonage pour acheter un numéro, créer une application vocale et y associer votre numéro.

Enfin, vous aurez besoin du code source utilisé dans cet article sur GitHub.

Cloner le dépôt et cd dans le répertoire racine de l'application.

Installation et configuration de la CLI de Vonage

Installez le CLI de Vonage à l'aide de la commande suivante :

npm install @vonage/cli -g

Ensuite, configurez le CLI avec la clé et le secret de l'API de Vonage, que vous trouverez dans le tableau de bord du développeur :

Vonage auth set –api-key=’VONAGE_API_KEY –api-secret=’VONAGE_API_SECRET’

Remplacer les VONAGE_API_KEY et VONAGE_API_SECRET par vos coordonnées pour authentifier le CLI.

Vous pouvez valider votre authentification pour vous assurer que tout fonctionne en utilisant la commande suivante :

vonage auth check

Si vous avez installé le CLI dans votre projet local plutôt que globalement, vous pouvez ajouter un indicateur supplémentaire à vérifier :

vonage auth check –local

Acheter un Numbers Vonage

Vous avez besoin d'un numéro à partir duquel vous pouvez passer des appels. Achetez-en un en exécutant la commande suivante, en remplaçant l'indicatif du pays par celui qui convient. Par exemple, si vous êtes aux États-Unis, remplacez [CODE PAYS] par US:

vonage numbers search [COUNTRYCODE]

Vous pouvez acheter le numéro de téléphone en exécutant le code ci-dessous depuis votre terminal. Il est important de noter que certains pays exigent une validation de l'adresse et que l'achat doit être effectué via le tableau de bord de Vonage et non via la ligne de commande.

vonage numbers buy [COUNTRYCODE] [MSIDSN]

Notez le numéro de téléphone que la commande renvoie.

Créer l'application Voice

Pour utiliser la Voice API, vous devez créer une application Voice API Voice API. Il ne s'agit pas de la même chose que l'application Web que vous êtes en train de créer. Il s'agit simplement d'un conteneur pour les informations de configuration et de sécurité dont vous avez besoin pour vous connecter aux API de Vonage.

vonage apps create "Play audio app" --private-key-file=~/private.key

Vous recevrez les données suivantes à noter :

Nom : play audio app

Applications : 7a319bf9-49e7-413d-914b-402fe8e68228

Améliorer l'IA : Désactivé

Clé privée/publique : Définir

Vous remarquerez que nous avons donné à la commande l'argument suivant private-key-file. Cela vous permettra de télécharger votre clé privée une fois la commande exécutée : localisez ce fichier de clé (dans la commande, j'ai utilisé l'argument de type UNIX ~/ locationqui est le dossier personnel ; vous voudrez le mettre à quelque chose comme. C:\Users\YOUR-USER-NAME si vous utilisez Powershell sous Windows) et placez le fichier dans le répertoire racine du code de l'article de blog qui l'accompagne. code de l'article de blog qui l'accompagne.

Nous n'avons pas encore configuré l'application pour qu'elle utilise l'API Voice. Exécutez donc la commande suivante pour ajouter la capacité Voice :

vonage apps capabilities update [VONAGE_APPLICATION_ID] --voice-answer-url=https://example.com/answer --voice-event-url=https://example.com/event-status

Vous remarquerez que nous définissons le voice-answer-url et le voice-event-url au niveau de l'application. Il s'agit pour l'instant d'espaces réservés et vous n'avez pas besoin de modifier ces valeurs. La raison en est que le code utilisé pour effectuer l'appel créera dynamiquement ces valeurs au cours des appels HTTP effectués.

Initialiser les dépendances

Pour construire cette application, prenons le strict minimum requis pour passer un appel Voice et pouvoir mettre à jour l'instance d'appel pour diffuser de l'audio dans l'appel. Vous aurez besoin des éléments suivants

• dotenv - une bibliothèque légère qui vous permet de lire un fichier de variables d'environnement (le standard de facto est de le nommer .env. Nous en aurons besoin pour injecter la clé API et le secret du tableau de bord Vonage au moment de l'exécution.

• express - Le cadre de nœuds le plus léger et le plus largement utilisé pour les fonctionnalités HTTP de base.

• @vonage/server-sdk - le bibliothèque client REST pour Node.js.

• @vonage/voice - SDK Voice de Vonage pour Node.js

Nous pouvons installer l'un d'entre eux en ligne de commande. Tout d'abord, nous devons initialiser le projet en tant que projet npm, qui vous posera ensuite une série de questions pour définir l'ensemble du projet. Vous pouvez choisir les valeurs par défaut pour l'instant ; il vous demandera également s'il y a des paquets que vous voulez installer, mais nous allons sauter cette étape pour clarifier la façon dont nous ajouterons les dépendances par la suite. Vous pouvez également utiliser yarn pour cela, je l'ai donc inclus dans un extrait de terminal séparé. Choisissez ce qui vous convient le mieux :

npm init

yarn init

Appuyez sur return pour choisir toutes les valeurs par défaut - vous pouvez appeler ce paquetage comme vous le souhaitez, car ce n'est pas important dans ce contexte. Une fois que vous avez fait cela, npm ou yarn va créer un fichier package.json pour vous. À partir de là, nous pouvons ajouter les différents paquets :

npm install dotenv express @vonage/server-sdk @vonage/voice

Exposez votre Application à l'Internet

Nous devons exposer notre application à l'Internet afin que les serveurs de Vonage puissent envoyer à notre application les webhooks de l'API Voice. Nous recommandons d'utiliser ngrok pour cela.

Vous pouvez en savoir plus sur la façon de mettre en place ngrok et de le faire fonctionner pour installer et lancer ngrok sur le port 3000 (c'est le port par défaut d'express.js). Par exemple :

ngrok http 3000

ngrok vous donnera une URL temporaire, telle que https://914288e7.ngrok.io. Notez-la.

Laissez ngrok en marche pendant que vous utilisez l'application ; sinon, les URL changeront et vous devrez le reconfigurer.

Configurer l'environnement

Copie. example.env à .env et saisissez les informations que vous avez recueillies au cours des étapes précédentes :

VONAGE_APPLICATION_ID= The Voice API application ID

VONAGE_APPLICATION_PRIVATE_KEY_PATH= private.key

VONAGE_NUMBER= The number you rented from Vonage

TO_NUMBER= The number you want the application to call

BASE_URL= The ngrok temporary URL

Vous êtes maintenant prêt à voir l'application en action !

Exécuter l'application

Lancez l'application en exécutant la commande suivante :

node server.js

Si votre application express.js est satisfaisante, vous devriez obtenir un journal indiquant que l'application écoute sur le port 3000. Visitez le site http://localhost:3000/call dans votre navigateur. Cela permet d'obtenir un GET au point de terminaison /call dans votre application et la fait sonner le point d'entrée TO_NUMBER dans .env.

Vous entendrez un message, suivi d'une musique pendant 20 secondes, puis l'appel sera coupé.

Comment cela fonctionne-t-il ?

Voyons comment tout cela s'articule dans le code. Le fonctionnement de l'application comporte trois parties :

1. Passer l'appel sortant.

2. Donnez à Vonage l'objet NCCO qui définira ce qui se passe lorsque le client final répond à l'appel.

3. Diffuser le son de la musique d'attente dans un appel actif.

Passer l'appel sortant

Le code suivant est exécuté lorsque vous envoyez une requête GET au point de terminaison /call au point de terminaison :

try {

   console.log("Making the outbound call...");

   const resp = await voice.createOutboundCall(

     {

       to: [{ type: "phone", number: TO_NUMBER }],

       from: { type: "phone", number: VONAGE_NUMBER },

       answer_url: [answer_url],

       answer_method: HttpMethod.POST, // This will hit the NCCO response

       event_url: [event_url], // Event URL to track events like answered

     }

   );

   console.log("Outbound call response:", resp);

   res.status(200).send("Call initiated!");

 } catch (error) {

   console.error("Error making the outbound call:", error);

   res.status(500).send("Failed to make call.");

 }

Le dotenv se charge d'importer les variables du fichier .env afin que nous sachions qui appeler. La bibliothèque answer_url indique à Vonage ce qu'il faut faire lorsque l'on répond au téléphone - ce que nous allons faire ici, c'est renvoyer un NCCO, que nous allons utiliser la classe NCCO Builder dans le SDK Node pour le créer.

Définir la réponse NCCO

Nous définissons le answer_url comme point de terminaison dans notre application express.js avec le code suivant :

app.post("/audio/answer", (req, res) => {

 const builder = new NCCOBuilder();

 builder.addAction(

   new Talk('Here is some soothing music for you')

 )

 builder.addAction(

   new Stream(audio_url)

 );

 // Send back the generated NCCO

 res.json(builder.build());

});

Tout d'abord, c'est app.post() qui définit la route de l'application. La suite se déroule en deux temps : Vonage attend des instructions sous la forme d'un NCCO qui lui indique ce qu'il doit faire lorsqu'il répond au téléphone.

1. Parler pour dire au client final que la musique est en route

Vous pouvez voir que nous avons créé un nouvel objet NCCOBuilder objet. Cette classe gère toutes les méthodes nécessaires et enveloppe la construction de l'objet JSON NCCO proprement pour le développeur. La première tâche consiste à dire à l'utilisateur final qu'une belle musique est en route, le code crée donc un objet . Talk() qui prend une chaîne comme argument de la synthèse vocale. En utilisant l'objet addAction()vous pouvez ajouter tous les objets de valeur que vous souhaitez demander à Vonage de faire lors de l'appel. Il peut s'agir de capturer les entrées de l'utilisateur par . DTMF, la capture d'enregistrements audio et la synthèse vocale.

2. Diffuser le son dans un appel actif

Ce NCCO sera construit de manière synchrone, de sorte que les instructions contenues dans la charge utile du NCCO seront exécutées une à la fois. L'instruction suivante consiste à donner une URL publique de notre fichier musical hébergé à diffuser dans l'appel. Cette instruction est très similaire à l'action Talk() action. Nous donnons au constructeur une nouvelle action séquentielle à exécuter, qui est une Stream() action. Le premier argument est une chaîne de l'URL vers laquelle nous voulons pointer, que nous avons déjà définie comme l'URL audio_url que nous avons déjà définie en tant que variable audio_url.

Et voilà ! Deux commandes à donner à Vonage pour l'appel en cours en répondant au téléphone, et maintenant nous avons une belle musique relaxante pendant que nous attendons dans une file fictive, vraisemblablement stressante, pour... des billets de concert ou un rendez-vous chez le médecin.

Conclusion

Dans ce billet, vous avez appris à diffuser de l'audio dans un appel existant et à connaître les NCCO actions qui régissent le déroulement de l'appel. N'hésitez pas à expérimenter en remplaçant les fichiers audio et les NCCO par d'autres. actions. Les ressources suivantes peuvent vous aider :

• Référence de l'API Voice

• Référence NCCO

• Utilisation de SSML dans la TTS (synthèse vocale)

• L'API REST REST pour Node.js