Transmisión de audio en una llamada telefónica con Node.js

Introducción

Cuando tiene a su cliente en una llamada de Voz, tiene toda su atención. ¿Por qué no aprovechar esa oportunidad para contarle las últimas novedades de su empresa, transmitirle un mensaje inspirador de su director general o incluso ponerle su último jingle publicitario?

En esta publicación del blog, aprenderás a reproducir un archivo de audio en una llamada activa mediante programación utilizando la Voice API de Vonage y Node.js.

Antes de empezar

Para trabajar con este ejemplo, necesitarás Node.js. Si aún no lo tienes, instálalo desde el sitio web de sitio web de Node.js.

Puedes aprovisionar un número en Vonage Developer Dashboard, pero te explicaremos cómo usar la CLI de Vonage para comprar un número, crear una aplicación de voz y luego vincular tu número a ella.

Por último, querrás el código fuente utilizado en este artículo en GitHub.

Clone el repositorio y cd en el directorio raíz de la aplicación.

Instalar y configurar la CLI de Vonage

Instala la CLI de Vonage globalmente usando el siguiente comando:

npm install @vonage/cli -g

A continuación configura la CLI con tu clave y secreto de API de Vonage, que encontrarás en el panel para desarrolladores:

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

Sustituya el VONAGE_API_KEY y VONAGE_API_SECRET con sus datos para autenticar la CLI.

Puedes validar tu autenticación para asegurarte de que todo funciona utilizando el siguiente comando:

vonage auth check

Si has instalado el CLI en tu proyecto local en lugar de globalmente, puedes añadir una bandera extra para comprobarlo:

vonage auth check –local

Comprar un número de Vonage

Necesita un número desde el que realizar llamadas. Adquiera uno ejecutando el siguiente comando, sustituyendo el código de país según corresponda. Por ejemplo, si se encuentra en EE.UU., sustituya [CÓDIGO DE PAÍS] por EE.UU.:

vonage numbers search [COUNTRYCODE]

Puedes comprar el número de teléfono ejecutando el siguiente código desde tu terminal. Es importante tener en cuenta que algunos países requieren validación de dirección, y la compra debe realizarse a través del panel de Vonage y no de la línea de comandos.

vonage numbers buy [COUNTRYCODE] [MSIDSN]

Anote el número de teléfono que devuelve el comando.

Crear la aplicación Voice

Para utilizar la Voice API, debe crear una aplicación Voice API de voz. Esto no es lo mismo que la aplicación web que estás creando. Es simplemente un contenedor para la información de configuración y seguridad que necesitas para conectarte a las API de Vonage.

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

Recibirá los siguientes datos que deberá anotar:

Nombre: play audio app

ID de solicitud: 7a319bf9-49e7-413d-914b-402fe8e68228

Mejorar la IA: Off

Clave privada/pública: Establecer

Observará que hemos dado al comando el argumento private-key-file. Esto descargará tu clave privada por ti una vez que el comando se haya ejecutado: localiza este archivo de clave (en el comando, he usado el argumento de tipo UNIX ~/ locationque es la carpeta de inicio; querrás ponerlo en algo como. C:\Users\YOUR-USER-NAME si estás usando Powershell en Windows) y coloca el archivo en el directorio raíz del código del artículo de blog adjunto.

Todavía no hemos configurado la aplicación para que utilice la Voice API, así que ejecute el siguiente comando para añadir la capacidad de Voice:

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

Observará que estamos configurando el voice-answer-url y el voice-event-url a nivel de aplicación. Estos son marcadores de posición por ahora, y no es necesario cambiar estos valores. La razón es que el código utilizado para realizar la llamada creará dinámicamente estos valores durante las llamadas HTTP que se realicen.

Inicializar las dependencias

Para construir esta aplicación, vamos a tomar los requisitos mínimos para hacer una llamada de Voice y ser capaz de actualizar la instancia de llamada para reproducir audio en la llamada. Usted necesitará lo siguiente:

• dotenv - una biblioteca ligera que permite leer un archivo de variables de entorno (el estándar de facto es llamarlo .env. Lo necesitaremos para inyectar la clave de API y el secreto del panel de Vonage en tiempo de ejecución.

• express - El framework de nodos más ligero y utilizado para la funcionalidad HTTP básica.

• @vonage/servidor-sdk - la biblioteca cliente REST para Node.js.

• @vonage/voice - SDK de voz de Vonage para Node.js

Podemos instalar uno de estos en la línea de comandos. En primer lugar, tendremos que inicializar el proyecto como un proyecto npm, que luego te hará una serie de preguntas para definir el proyecto en general. Puedes elegir los valores predeterminados por ahora; también te preguntará si hay algún paquete que quieras instalar, pero omitiremos esto para aclarar cómo añadimos las dependencias después. También puedes usar yarn para esto, así que lo he incluido como un fragmento de terminal separado. Elija el que funcione para usted:

npm init

yarn init

Pulsa return para elegir todos los valores por defecto - puedes llamar a este paquete como quieras, ya que no es importante en este contexto. Una vez hecho esto, npm o yarn crearán un archivo package.json para usted. Desde aquí, podemos añadir los paquetes individuales:

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

Exponga su aplicación a Internet

Necesitamos exponer nuestra aplicación a Internet para que los servidores de Vonage puedan enviar a nuestra aplicación los webhooks de Voice API. Recomendamos usar ngrok para esto.

Puedes aprender más sobre cómo poner en marcha ngrok para instalar y ejecutar ngrok en el puerto 3000 (este es el puerto por defecto de express.js). Por ejemplo:

ngrok http 3000

ngrok le dará una URL temporal, como por ejemplo https://914288e7.ngrok.io. Anótelo.

Deje ngrok en ejecución mientras esté utilizando la aplicación; de lo contrario, las URL cambiarán y tendrá que volver a configurarlo.

Configurar el entorno

Recibido. example.env a .env e introduzca los datos que ha recogido en los pasos anteriores:

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

Ya puede ver la aplicación en acción.

Ejecutar la aplicación

Inicie la aplicación ejecutando el siguiente comando:

node server.js

Si tu aplicación express.js está satisfecha, deberías obtener un registro que indique que la aplicación está escuchando en el puerto 3000. Visita http://localhost:3000/call en tu navegador. Esto hace un GET al endpoint /call en su aplicación y hace que suene el timbre TO_NUMBER en .env.

Oirás un mensaje, seguido de música que suena durante 20 segundos y, a continuación, la llamada se desconecta.

¿Cómo funciona?

Veamos cómo se articula todo esto en el código. Hay tres partes en el funcionamiento de la aplicación:

1. Realice la llamada saliente.

2. Dale a Vonage el objeto NCCO que definirá lo que sucede cuando el cliente final contesta la llamada.

3. Transmite el audio de la música en espera a una llamada activa.

Realizar la llamada saliente

El siguiente código se ejecuta cuando se envía un mensaje GET al endpoint /call punto final:

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.");

 }

La página dotenv se encarga de importar las variables del archivo .env variables del archivo, para que sepamos a quién marcar. El answer_url le dice a Vonage qué hacer cuando se contesta el teléfono - lo que vamos a hacer aquí es devolver un NCCO, que vamos a utilizar la clase NCCO Builder en el Node SDK para crear.

Definir la respuesta NCCO

Definimos el answer_url como un endpoint en nuestra app express.js con el siguiente código:

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());

});

En primer lugar, es app.post() que define la ruta para la aplicación. Lo que sucede a continuación consta de dos partes: Vonage espera instrucciones en la forma de una OCNC para decirle qué hacer cuando se contesta el teléfono, por lo que esto tiene dos partes.

1. Utilizar la conversación para informar al cliente final de que la música está en camino

Puedes ver que hemos creado un nuevo NCCOBuilder objeto. Esta clase maneja todos los métodos necesarios y envuelve la construcción del objeto NCCO JSON ordenadamente para el desarrollador. La primera tarea es decirle al usuario final que hay música en camino, así que el código crea un objeto . Talk() que toma una cadena como argumento para el texto a voz. Usando el objeto addAction()puedes agregar cualquier objeto de valor que quieras indicarle a Vonage que haga en la llamada. Estos pueden incluir la captura de la entrada del usuario a través de. DTMF, capturar grabaciones de audio y texto a voz.

2. Transmita el sonido a una llamada activa

Esta NCCO se construirá de forma sincrónica, por lo que las instrucciones de la carga útil de la NCCO se ejecutarán de una en una. La siguiente instrucción es dar una URL pública de nuestro archivo de música alojado para transmitirlo a la llamada. Esto es muy similar a la acción Talk() acción. Le damos al constructor una nueva acción secuencial para llevar a cabo, que es una Stream() acción. El primer argumento es una cadena con la URL a la que queremos apuntar, que ya hemos definido como audio_url variable.

¡Y ahí lo tienes! Dos comandos para dar a Vonage para la llamada en curso al contestar el teléfono, y ahora tenemos encantadora música relajante mientras esperamos en una cola ficticia y presumiblemente estresante para... entradas para un concierto o una cita con el médico.

Conclusión

En este post, usted aprendió cómo reproducir audio en una llamada existente y acerca de la NCCO actions que rigen el flujo de llamadas. Siéntase libre de experimentar mediante la sustitución de diferentes archivos de audio y NCCO actions. Los siguientes recursos pueden ayudarte:

• Referencia Voice API

• Referencia OCNC

• Uso de SSML en TTS (texto a voz)

• La API REST biblioteca de clientes para Node.js