Llamadas de marca RTC con Voice API de Vonage y First Orion

Crea llamadas salientes de marca con Vonage Voice API y First Orion. Muestra el nombre de tu empresa, el logotipo y el objetivo de la llamada en las llamadas PSTN.

Introducción

Example of a branded incoming call displaying the company name, logo, and phone number on a mobile deviceSi realizas llamadas salientes desde una aplicación, es muy probable que algunas de ellas sean ignoradas o marcadas como spam. Cuando el destinatario no reconoce el número, a menudo no contesta, aunque la llamada sea legítima.

Llamadas de marca RTC aborda esta cuestión adjuntando información de identidad verificada a sus llamadas. En lugar de mostrar sólo un número de teléfono, el destinatario ve el nombre de su empresa, el logotipo y un breve motivo de la llamada directamente en su dispositivo. En la práctica, esto hace que sus llamadas sean más fáciles de reconocer y tengan más probabilidades de ser atendidas.

En este tutorial, configurarás las llamadas de marca RTC mediante la Voice API de Vonage y Primer Orion. Configurarás un programa de llamadas de marca, lo vincularás a un número virtual de Vonage y luego realizarás una llamada saliente desde una simple aplicación Node.js.

Al final, tendrá una configuración de trabajo donde sus llamadas salientes muestran información de marca en tiempo real, junto con una aplicación mínima que puede utilizar como punto de partida para su propia integración.

>> TL;DR: Salta adelante y encuentra el código de la aplicación de ejemplo en GitHub.

Requisitos previos

• Una cuenta API de Vonage con Voice activado

• Una Account First Orion con un registro comercial aprobado

• Un número virtual de Vonage ya provisto para llamadas de marca RTC

Llamada de marca en Primera Orión

First Orion ofrece un conjunto de API y herramientas de plataforma para gestionar las llamadas de marca en las redes de los operadores. La llaman plataforma INFORM, que gestiona cómo se presenta la identidad de su empresa en los dispositivos compatibles. En INFORM se definen aspectos como el nombre, el logotipo y el motivo de la llamada que aparecen cuando se recibe una llamada. La plataforma también le da acceso a análisis y controles a nivel de programa, para que pueda hacer un seguimiento de la entrega y realizar los ajustes necesarios.

Para activar las Llamadas de marca para un número de teléfono, tendrá que crear un programa. Un programa es como una campaña. Un programa pertenece a una unidad de negocio, que se encuentra dentro de un negocio.

Hierarchy of branded calling in First Orion, showing how a business contains business units, which contain programsPara empezar, tendrá que registrar su empresa en First Orion. Una vez que su empresa esté aprobada y haya creado su unidad de negocio, podrá crear su primer programa:

First Orion Business Unit dashboard where you can create programs and manage phone numbers for branded callingConfigurar un programa requiere 3 pasos:

1. Detalles: información general sobre el programa

2. Visualización: el nombre y la hora que se mostrarán a los usuarios

3. Numbers: qué número(s) se asignarán a este programa

También puedes crear un nuevo programa:

• a través de la API

• a través de el Portal del Cliente

Adding phone numbers and defining call purpose during branded calling program setup in First Orion

Una vez creado su programa, podrá asignarle una imagen. Haga clic en el programa para editarlo. Y luego vaya al paso 3, "Imagen", donde podrá añadir una Imagen & Motivo de llamada:

Uploading a logo and defining the call reason for a branded calling program, with a real-time mobile preview

Vinculación de llamadas de marca en el panel de Vonage

Con el programa First Orion configurado, deberás configurar el enlace en el panel de Vonage. En el panel de Vonage, ve a Voice → Llamadas de confianza →. Llamadas de marca PSTN.

En primer lugar, deberá seguir las instrucciones para integrar su First Orion Account. La dirección ID de usuario es su clave API de First Orion, y la Contraseña es la clave secreta asociada. Puede ver cómo generar una Primera Clave API de Orion en la documentación.

Configuring the First Orion integration in the Vonage Dashboard using API credentialsUna vez establecida la integración, podrá configurarla. Abra la integración que ha creado haciendo clic en la opción "editar".

First Orion integration successfully configured in the Vonage Dashboard with an enabled virtual numberA continuación, selecciona activar en el número virtual de Vonage que agregaste antes en el panel de control de First Orion.

Managing and enabling virtual numbers for PSTN Branded Calling in the Vonage Dashboard

Cómo ejecutar la aplicación de prueba Voice de Vonage

Ahora que tu número virtual de Vonage está vinculado a tu programa de llamadas de marca First Orion, puedes realizar una llamada saliente de marca desde una simple aplicación de prueba Node.js. La aplicación de ejemplo expone un archivo local /call local y usa ngrok para que tus puntos finales de webhook sean accesibles públicamente.

1. Clonar la aplicación de ejemplo e instalar las dependencias

git clone git@github.com:Vonage-Community/blog-voice-node-branded_calling.git
cd branded-calling
npm install

2. Configure su archivo ENV

Copie el archivo de entorno de ejemplo y edítelo:

cp .env.example .env

Configurará 3 categorías de ajustes:

A) Autenticación de Vonage (JWT / Aplicación)

• VONAGE_APPLICATION_ID
  El ID de aplicación del panel de Vonage

• VONAGE_PRIVATE_KEY_PATH
  Ruta a su archivo de clave privada (PEM). En este tutorial, usaremos ./private.key.

B) Llamada por defecto

• FROM_NUMBER
  Tu número virtual de Vonage que registraste/habilitaste para llamadas de marca (formato E.164, como +1408...).

• NÚMERO_TO
  El número de destino por defecto para su llamada de prueba (su móvil, etc.). Puede anularlo más adelante en la solicitud curl.

C) Marca

1. NOMBRE_EMPRESA

2. SALUDO
   El mensaje de texto a voz que se reproduce cuando se contesta la llamada.

3. Iniciar un túnel ngrok

Vonage debe poder llegar a tus puntos finales de webhook a través de la Internet pública. La forma más fácil para el desarrollo local es ngrok.

En una nueva ventana de terminal:

ngrok http 3000

Copie la URL HTTPS de reenvío (se verá como https://xxxx.ngrok-free.app).

Ahora establece esto en tu .env:

• PUBLIC_BASE_URL = su URL HTTPS ngrok

PUBLIC_BASE_URL=https://xxxx.ngrok-free.app

>> Importante: Si reinicias ngrok, obtendrás una nueva URL y deberás actualizar PUBLIC_BASE_URL de nuevo.

4. Crear una aplicación de voz de Vonage

En el panel de Vonage:

• Crear una nueva Aplicación

• Activar las funciones de Voice

• Genera/descarga la clave privada (private.key) y colócala en la raíz de tu proyecto

• Copie el ID de la Aplicación en su .env como VONAGE_APPLICATION_ID

• En el evento webhook en el tablero de instrumentos, agregue su ngrok HTTPS seguido de /event (por ejemplo https://xxxx.ngrok-free.app/event)

5. Inicie el servidor local

De vuelta en el terminal del proyecto, inicia tu aplicación:

npm run start

6. Activar la llamada saliente con curl

Opción A: llamar al TO_NUMBER por defecto de .env

curl -X POST http://localhost:3000/call \
  -H 'Content-Type: application/json' \
  -d '{}'

Opción B: anular el número de destino por solicitud

curl -X POST http://localhost:3000/call \
  -H 'Content-Type: application/json' \
  -d '{"to":"+14155550100"}'

Ahora debería recibir una llamada con la marca que haya configurado (nombre, logotipo y motivo de la llamada).

Full-screen view of an incoming branded call displaying the company name, logo, and standard call controls on a mobile device

Nota: La visualización de la marca depende del operador y del comportamiento del dispositivo. Puedes comprobar el "estado por operador" en los detalles del programa.

Screenshot of the First Orion program details page displaying call metrics, answer rate, and carrier approval status for AT&T, Verizon, and T-Mobile.

Conclusión

En este punto, has configurado PSTN Branded Calling de extremo a extremo usando Vonage y First Orion. Creaste un programa de llamadas de marca, lo vinculaste a un número virtual de Vonage y activaste una llamada saliente desde una aplicación Node.js que muestra tu marca configurada en tiempo real.

Una vez sentadas estas bases, puede empezar a integrar las llamadas de marca en sus flujos de trabajo actuales. Por ejemplo, activando llamadas a partir de eventos de la aplicación, personalizando dinámicamente los motivos de las llamadas o separando diferentes casos de uso en programas distintos.

Si quiere ir un paso más allá, First Orion también proporciona una API de autenticación de llamadas que puede invocarse justo antes de realizar una llamada. Esto le permite registrar explícitamente la intención de la llamada (emisor y receptor) en tiempo real, lo que puede mejorar aún más la confianza y la verificación de llamadas en redes compatibles.

Este patrón encaja de forma natural con la configuración de este tutorial, ya que se ejecuta justo antes de la solicitud de llamada saliente existente.

En una configuración de producción, también querrá sustituir las herramientas locales como ngrok por un punto final estable y de acceso público, y asegurarse de que sus credenciales y la configuración de webhooks se gestionan de forma coherente en todos los entornos.

El modelo general sigue siendo sencillo: tu aplicación controla el inicio de la llamada, Vonage se encarga de la entrega y First Orion proporciona la capa de identidad superior. Una vez conectadas, las llamadas de marca se convierten en una extensión directa de los flujos de llamadas salientes que ya tienes.