Desviar una llamada a través de un proxy de voz con Koa.js

Introducción

Este tutorial te muestra cómo añadir capacidades de voz a tu aplicación. Utilizaremos Koa, un framework web para Node.js, para crear un servidor que gestione las llamadas entrantes y los eventos y la Voice API de Vonage para desviar las llamadas a otro número de teléfono. Vamos a empezar.

Esquema del proyecto

Al final de este proyecto, esto es lo que su carpeta de proyecto debe ser similar:

Requisitos previos

Para seguir este tutorial, necesitarás:

• Node.js instalado

• Ngrok se instala para exponer su servidor de desarrollo local a Internet.

• Una cuenta de desarrollador de Vonage para acceder a nuestra Voice API.

  Vonage API Account

  To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

  This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

  

  Ready to start building?

  Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Configuración Ngrok

Para poder exponer endpoints desde nuestras máquinas locales sin tener que desplegar nuestra aplicación a un entorno en vivo, haremos que nuestro servidor local sea accesible a internet usando ngrok

Una vez instalado, en una nueva ventana de terminal/síntesis de comandos, inicie ngrok en el puerto 3000:

ngrok http 3000

Configurar Vonage

Configurar elCLI de Vonage

Puedes crear y administrar aplicaciones de Vonage usando la CLI de Vonage. Instálala si aún no lo has hecho:

npm install @vonage/cli -g

Establezca la configuración de la clave y el secreto de la API

Ejecute el comando para establecer la configuración de la clave y el secreto de la API. Después de esto, verá Configuration saved en su terminal o en el símbolo del sistema.

En VONAGE_KEY y VONAGE_SECRET se pueden encontrar en el Panel de Vonage.

Vonage Dashboard

Crear una aplicación

Usa la CLI para crear una nueva aplicación con capacidades de voz y anota el ID de la aplicación que se proporciona al crearla. Ejecuta el comando para crear una nueva aplicación de Vonage.

A continuación, aparecerá una ventana con algunos campos que deberá rellenar de la siguiente manera.

Deberías recibir una respuesta similar a esta:

Alquilar un número virtual

A continuación, necesitaremos un número virtual que actúe como nuestra "cara pública" para las llamadas entrantes. Este número estará vinculado a nuestra aplicación de Vonage, y aquí te explicamos cómo adquirir uno:

1. Busque los Numbers disponibles en la región que desee. Afortunadamente, podemos comprar Numbers directamente desde la CLI así vonage numbers:search US (sustituya US por el código de su país si es necesario).

2. Compre un número: vonage numbers:buy 12079460000 US.

Recuerde que algunos Numbers no pueden adquirirse a través de la línea de comandos, por lo que deberá comprarlos a través del panel de control. Puedes hacerlo ingresando al Panel de Vonage y a la página Página Comprar Numbers. Marca 'Voice' en el filtro de búsqueda y selecciona el país donde deseas comprar un número.

Vincular un número de teléfono virtual a la aplicación

Con nuestro número elegido, es hora de conectarlo a nuestra aplicación de Vonage. Puedes vincular un número de teléfono virtual directamente desde el panel de Vonage o a través de la CLI. La vinculación garantiza que las llamadas a tu número virtual se enruten correctamente a través de tu aplicación.

vonage apps:link --number=12079460000 APPLICATION_ID

También puedes hacerlo desde el salpicadero. Vaya a la Página de aplicaciones y haz clic en la aplicación que creaste anteriormente. Haz clic en el botón "Vincular" de la sección Voice junto al número que quieras vincular.

Crear el proyecto Node.js

1. Cree un nuevo directorio para su proyecto y navegue hasta él. (Ejemplo de carpeta VoiceWithVonage)

2. Inicializa un nuevo proyecto Node.js con npm init -y para aceptar todos los ajustes por defecto.

Instalar dependencias

Nuestro proyecto depende de algunas dependencias, que instalaremos con un solo comando:

Variables de entorno

Utilizaremos variables de entorno para almacenar información sensible como claves API y números de teléfono para mantener nuestra aplicación segura y manejable.

Cree un archivo .env en la raíz de tu proyecto y añade tus variables consulta la entrada del blog de Michael para una mejor explicación de cómo usar variables de entorno en Node.js

// .env
VONAGE_API_KEY= Your Vonage API key, used for authenticating API requests.
VONAGE_API_SECRET= Your Vonage API secret
VONAGE_APPLICATION_ID= The ID of your Vonage application. Vonage applications allow you to manage your communication services and define how they interact with your web application.
VONAGE_PRIVATE_KEY= The path to your Vonage application's private key file. When you create a Vonage application that uses voice capabilities, you generate a public/private key pair. The private key authenticates your application when making API requests. It will  look like nameOfTheFile.key.
FROM_NUMBER= The Vonage virtual number (purchased through Vonage) that calls will come from. It is the number displayed to the user receiving the call.
YOUR_SECOND_NUMBER= The destination phone number to which the call will be forwarded. It should be in [E.164 format](https://en.wikipedia.org/wiki/E.164).

Inicializar Vonage

El SDK del servidor de Vonage facilita la integración con los servicios de Vonage. Inícialo en tu proyecto para habilitar la funcionalidad de voz, asegurándote de que los valores de los marcadores de posición sean reemplazados por tus credenciales de API almacenadas en tu archivo .env archivo.

Cree un archivo llamado forward_a_call.js y el código siguiente.

// forward_a_call.js
require("dotenv").config();
const { Vonage } = require("@vonage/server-sdk");

// Initialize the Vonage Server SDK with your credentials
const vonage = new Vonage({
 apiKey: process.env.VONAGE_API_KEY,
 apiSecret: process.env.VONAGE_API_SECRET,
 applicationId: process.env.VONAGE_APPLICATION_ID,
 privateKey: process.env.VONAGE_PRIVATE_KEY,
});

Configurar Koa

Empezaremos por configurar nuestro entorno de servidor:

require("dotenv").config();
const Koa = require("koa");
const Router = require("@koa/router");
const koaBody = require("koa-bodyparser");

const app = new Koa();
const router = new Router();

app.use(koaBody());

Aquí, importamos los módulos necesarios e inicializamos nuestra aplicación Koa. dotenv carga variables de entorno (como las credenciales de la API de Vonage y los números de teléfono) desde un archivo .env archivo.

El middleware koaBodyparser se aplica para analizar el cuerpo de las peticiones entrantes, lo cual es esencial para leer las cargas JSON en nuestro webhook /event.

Además, utilizamos @koa/router, un middleware de enrutamiento, para definir y gestionar rutas dentro de nuestra aplicación. Esto nos permite especificar acciones para diferentes rutas, como /answer para responder llamadas y /event para procesar eventos webhook.

Responder a las llamadas con NCCO

La ruta /answer ruta se define como la respuesta a las llamadas entrantes. Cuando la plataforma de Vonage recibe una llamada a tu número virtual, solicita que este /answer punto final recupere instrucciones, conocidas como NCCO (objeto de control de llamadas), sobre el manejo de la llamada.

En este ejemplo, el NCCO le indica a Vonage que primero reproduzca un mensaje ("Por favor, espera mientras conectamos tu llamada") y luego conecte la llamada a otro número especificado (YOUR_SECOND_NUMBER), usando tu número de Vonage (FROM_NUMBER) como identificador de llamadas.

router.get("/answer", async (ctx) => {
  const ncco = [
    {
      action: "talk",
      text: "Please wait while we connect your call.",
    },
    {
      action: "connect",
      eventUrl: [],
      from: process.env.FROM_NUMBER,
      endpoint: [
        {
          type: "phone",
          number: process.env.YOUR_SECOND_NUMBER,
        },
      ],
    },
  ];
  ctx.body = ncco;
});

Procesar eventos, aplicar rutas e iniciar el servidor

La ruta /event captura y registra los eventos relacionados con la llamada. Este punto final es esencial para depurar y supervisar el ciclo de vida de sus llamadas. Los eventos pueden incluir estados de llamada como contestada, completada o fallida. Al registrar estos eventos, podemos obtener información sobre el flujo de llamadas y solucionar cualquier problema.

Por último, aplicamos nuestras rutas a la aplicación Koa e iniciamos el servidor.

router.post("/event", async (ctx) => {
  console.log(ctx.request.body);
  ctx.status = 204; // No content to send back
});

app.use(router.routes()).use(router.allowedMethods());

app.listen(3000, () => console.log("Server running on port 3000"));

La aplicación escucha en el puerto 3000 y registra un mensaje en la consola una vez que el servidor se ejecuta. Aquí, las rutas que definimos se vuelven accesibles, lo que permite que la plataforma de Vonage interactúe con nuestro servidor según las URL especificadas en el panel de Vonage para los webhooks de respuestas y eventos de nuestra aplicación.

Ejecutar y probar la aplicación

Con todo en su lugar, inicie su servidor ejecutando el comando:

Prueba el desvío de llamadas marcando tu número virtual de Vonage. La llamada debería desviarse al número especificado en tu archivo .env archivo.

Conclusión y conecte con nosotros

Felicitaciones. Ahora dominas el arte del desvío de llamadas con Vonage. Si tienes alguna pregunta o sugerencia o quieres compartir lo que has creado, únete a nuestra Comunidad Slack para desarrolladores de Vonage o comunícate en X, antes conocido como Twitter.

Lecturas complementarias

Crea un plan de escape con la Voice API de Vonage y consigue una llamada fantasma

Transferir una llamada con NCCO