Rastrea el uso de tus números de Vonage

Obtén información sobre la efectividad de las comunicaciones con tus clientes llevando un registro de las llamadas recibidas por tus Numbers de Vonage. Al registrar un número diferente para cada una de tus campañas de marketing, puedes ver cuál funciona mejor y usar esa información para mejorar tus futuros esfuerzos de marketing. mejor y usar esa información para mejorar tus futuros esfuerzos de marketing.

El ejemplo de hoy utiliza NodeJS y todo el código es disponible en GitHub, sin embargo, este mismo enfoque podría aplicarse a cualquier otra pila tecnológica.

Requisitos previos

Para poder trabajar con esta guía necesitas:

A Account de Vonage
El CLI de Vonage instalado y configurado.
Un servidor web de acceso público para que Vonage pueda realizar solicitudes de webhook a tu aplicación. Si estás desarrollando localmente recomendamos ngrok.

Empezar

Antes de descargar el código y ponerte manos a la obra, tendrás que configurar una aplicación de Vonage y obtener algunos Numbers para utilizarla. Al crear una aplicación de Vonage, debes especificar algunos Numbers webhook endpoints; estos son URLs en tu propia aplicación y son la razón por la que tu código debe ser accesible públicamente. Cuando una persona llama a a tu número de Vonage, Vonage realizará una solicitud web a la answer_url punto final que especifiques y sigue las instrucciones que encuentre allí.

También hay un event_url webhook, que recibe actualizaciones cada vez que cambia el estado de la llamada. En esta aplicación, el código código envía los eventos a la consola para proporcionar información útil durante el desarrollo.

Para crear la aplicación inicial, utiliza la CLI de Vonage para ejecutar el comando que aparece a continuación, sustituyendo tu URL en dos lugares:

vonage apps create 'Your application'

✅ Creating Application
Saving private key ... Done!
Application created

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  None Enabled

vonage apps create 'Your application'

✅ Creating Application
Saving private key ... Done!
Application created

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  None Enabled

vonage apps create 'Your application' ✅ Creating Application Saving private key ... Done! Application created Name: Your application Application ID: 00000000-0000-0000-0000-000000000000 Improve AI: Off Private/Public Key: Set Capabilities: None Enabled

Este comando devuelve el UUID (identificador único universal) que identifica tu aplicación. Con el ID de la aplicación, ya puedes añadir la función de voz a tu aplicación:

Asegúrate de configurar el voice-answer-url, voice-event-url para que apunte a tu dominio. No es necesario que configures la URL alternativa.

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 voice `
  --voice-answer-url='https://example.com/webhooks/voice/answer' `
  --voice-event-url='https://example.com/webhooks/voice/event' `
  --voice-fallback-url='https://example.com/webhooks/voice/fallback'
  
✅ Fetching Application
✅ Adding voice capability to application 00000000-0000-0000-0000-000000000000

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
 VOICE:
    Uses Signed callbacks: On
    Conversation TTL: 41 hours
    Leg Persistence Time: 6 days
    Event URL: [POST] https://example.com/webhooks/voice/event
    Answer URL: [POST] https://example.com/webhooks/voice/answer
    Fallback URL: [POST] https://example.com/webhooks/voice/fallback

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 voice ^
  --voice-answer-url='https://example.com/webhooks/voice/answer' ^
  --voice-event-url='https://example.com/webhooks/voice/event' ^
  --voice-fallback-url='https://example.com/webhooks/voice/fallback'
  
✅ Fetching Application
✅ Adding voice capability to application 00000000-0000-0000-0000-000000000000

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
 VOICE:
    Uses Signed callbacks: On
    Conversation TTL: 41 hours
    Leg Persistence Time: 6 days
    Event URL: [POST] https://example.com/webhooks/voice/event
    Answer URL: [POST] https://example.com/webhooks/voice/answer
    Fallback URL: [POST] https://example.com/webhooks/voice/fallback

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 voice \ --voice-answer-url='https://example.com/webhooks/voice/answer' \ --voice-event-url='https://example.com/webhooks/voice/event' \ --voice-fallback-url='https://example.com/webhooks/voice/fallback' ✅ Fetching Application ✅ Adding voice capability to application 00000000-0000-0000-0000-000000000000 Name: Your application Application ID: 00000000-0000-0000-0000-000000000000 Improve AI: Off Private/Public Key: Set Capabilities: VOICE: Uses Signed callbacks: On Conversation TTL: 41 hours Leg Persistence Time: 6 days Event URL: [POST] https://example.com/webhooks/voice/event Answer URL: [POST] https://example.com/webhooks/voice/answer Fallback URL: [POST] https://example.com/webhooks/voice/fallback

Necesitarás un par de números de Vonage para probar esta aplicación. Puedes usar la CLI de Vonage para buscar y comprar un número usando los comandos que se muestran a continuación; cuando busques un número, ingresa cualquier código de país en Formato ISO 3166-1 alfa-2.

vonage numbers search US

✅ Searching for numbers

There is 1 number available for purchase in United States

Number       Type    Features         Monthly Cost  Setup Cost
-----------  ------  ---------------  ------------  ----------
16127779311  Mobile  MMS, SMS, VOICE  €0.90         €0.00

Use vonage numbers buy to purchase.

vonage numbers search US

✅ Searching for numbers

There is 1 number available for purchase in United States

Number       Type    Features         Monthly Cost  Setup Cost
-----------  ------  ---------------  ------------  ----------
16127779311  Mobile  MMS, SMS, VOICE  €0.90         €0.00

Use vonage numbers buy to purchase.

vonage numbers search US ✅ Searching for numbers There is 1 number available for purchase in United States Number Type Features Monthly Cost Setup Cost ----------- ------ --------------- ------------ ---------- 16127779311 Mobile MMS, SMS, VOICE €0.90 €0.00 Use vonage numbers buy to purchase.

vonage numbers buy US 16127779311 
✅ Searching for numbers
Are you sure you want to purchase the number 16127779311 for €0.90? [y/n] y

✅ Purchasing number
Number 16127779311 purchased

Number: 16127779311 
Country: 🇺🇸 United States
Type: Mobile
Features: MMS, SMS, VOICE
Monthly Cost: €0.90
Setup Cost: €0.00
Linked Application ID: Not linked to any application
Voice Callback: Not Set
Voice Callback Value: Not Set
Voice Status Callback: Not Set

vonage numbers buy US 16127779311 
✅ Searching for numbers
Are you sure you want to purchase the number 16127779311 for €0.90? [y/n] y

✅ Purchasing number
Number 16127779311 purchased

Number: 16127779311 
Country: 🇺🇸 United States
Type: Mobile
Features: MMS, SMS, VOICE
Monthly Cost: €0.90
Setup Cost: €0.00
Linked Application ID: Not linked to any application
Voice Callback: Not Set
Voice Callback Value: Not Set
Voice Status Callback: Not Set

vonage numbers buy US 16127779311 ✅ Searching for numbers Are you sure you want to purchase the number 16127779311 for €0.90? [y/n] y ✅ Purchasing number Number 16127779311 purchased Number: 16127779311 Country: 🇺🇸 United States Type: Mobile Features: MMS, SMS, VOICE Monthly Cost: €0.90 Setup Cost: €0.00 Linked Application ID: Not linked to any application Voice Callback: Not Set Voice Callback Value: Not Set Voice Status Callback: Not Set

Puede utilizar cualquier código de país en Formato ISO 3166-1 alfa-2 para este comando. El resultado es el número que ha comprado, así que cópielo (siempre puede obtener una lista con vonage numbers) y vincúlalo a la aplicación que has creado:

vonage apps numbers link 00000000-0000-0000-0000-000000000000 16127779311

✅ Fetching Application
Fetching Owned numbers [===============================================] 1/1 100%

Number linked

Number: 16127779311
Country: 🇺🇸 United States
Type: Toll-free
Features: MMS, SMS, VOICE
Monthly Cost: Not Set
Setup Cost: Not Set
Linked Application ID: 00000000-0000-0000-0000-000000000000
Voice Callback: app
Voice Callback Value: 00000000-0000-0000-0000-000000000000
Voice Status Callback: Not Set

vonage apps numbers link 00000000-0000-0000-0000-000000000000 16127779311

✅ Fetching Application
Fetching Owned numbers [===============================================] 1/1 100%

Number linked

Number: 16127779311
Country: 🇺🇸 United States
Type: Toll-free
Features: MMS, SMS, VOICE
Monthly Cost: Not Set
Setup Cost: Not Set
Linked Application ID: 00000000-0000-0000-0000-000000000000
Voice Callback: app
Voice Callback Value: 00000000-0000-0000-0000-000000000000
Voice Status Callback: Not Set

vonage apps numbers link 00000000-0000-0000-0000-000000000000 16127779311 ✅ Fetching Application Fetching Owned numbers [===============================================] 1/1 100% Number linked Number: 16127779311 Country: 🇺🇸 United States Type: Toll-free Features: MMS, SMS, VOICE Monthly Cost: Not Set Setup Cost: Not Set Linked Application ID: 00000000-0000-0000-0000-000000000000 Voice Callback: app Voice Callback Value: 00000000-0000-0000-0000-000000000000 Voice Status Callback: Not Set

Repite el paso de comprar y vincular tantos números como quieras utilizar.

Los nuevos usuarios deberán recargar su Account antes de poder comprar un número.

Configurar y ejecutar la aplicación

En primer lugar, obtenga el código de este repositorio. Puedes clonar el repositorio en tu ordenador o descargar el archivo zip.

Instale las dependencias con este comando: npm install

A continuación, copia la plantilla de configuración .env-example en un archivo llamado .env. En este archivo tendrás que configurar el número de teléfono al que Vonage debe conectarse, por lo que puede ser cualquier teléfono que tengas cerca y al que puedas contestar.

También puede establecer el número de puerto en la opción .env añadiendo un PORT ajuste

Para iniciar el servidor web: npm start

Comprueba que todo funciona según lo previsto visitando http://localhost:5000. Deberías ver «Hello Vonage» como respuesta.

Atención de llamadas entrantes

Cuando Vonage recibe una llamada entrante en tu número de Vonage, envía una solicitud al punto final del webhook que configuraste al ha creado una aplicación de Voice.

Cuando la persona que llama realiza la llamada, la aplicación recibe el webhook entrante. Extrae el número desde el que la persona que llama está llamando (el to número) y el número que han marcado (el from número) y transmite estos valores a la lógica de seguimiento de llamadas.

El webhook entrante lo recibe el /track-call ruta:

app.get('/track-call', (req, res) => {
    const from = req.query.from;
    const to = req.query.to;

    const ncco = callTracker.answer(from, to);
    return res.json(ncco);
});

Realizar un seguimiento de la llamada antes de conectar con el llamante

La lógica para rastrear realmente la llamada está separada en la aplicación de ejemplo. Tenga en cuenta que la aplicación pierde los datos cuando se reinicia el servidor. Para sus propias aplicaciones puede extender esta parte para escribir en una base de datos, una plataforma de registro o algo que se adapte a sus necesidades. o cualquier otra cosa que se adapte a sus necesidades. Después de rastrear la llamada, la aplicación devuelve un Objeto de control de llamadas de Nexmo (NCCO) para decirle a los servidores de Vonage qué hacer a continuación con la llamada.

Encontrarás este código en lib/CallTracker.js:

class CallTracker {

  config;

  trackedCalls;

  constructor(config) {
    this.config = config;

    this.trackedCalls = {};
  }

  /**
   * Track the call and return an NCCO that proxies a call.
   */
  answer (from, to) {
    if(!this.trackedCalls[to]) {
      this.trackedCalls[to] = [];
    }

    this.trackedCalls[to].push({
      timestamp: Date.now(),
      from: from,
    });

    return [
      {
        action: 'connect',
        from: to,
        endpoint: [
          {
            type: 'phone',
            number: this.config.proxyToNumber,
          },
        ],
      },
    ];
  };
}

La OCN utiliza el connect para conectar la llamada entrante con otra llamada al número especificado en el archivo de configuración archivo de configuración. La dirección from El número tiene que ser un número de Vonage, por lo que el código utiliza el número rastreado como identificador de llamada para la llamada saliente. Comprueba el Documentación de la OCNC para el connect acción para más detalles sobre el objeto de control de llamada.

Conclusión

Con este enfoque has podido vincular algunos números de Vonage a tu aplicación node.js, hacer un registro de llamadas entrantes a esos números y conectar a quienes llaman con un número saliente. Mediante el registro de la marca de tiempo, así como los números de origen y destino, puedes seguir adelante y realizar cualquier análisis que necesites sobre estos datos para obtener los mejores resultados para tu negocio. resultados para su empresa.

¿Y ahora qué?

A continuación se ofrecen algunas sugerencias más de recursos que podrían ser de su agrado como paso siguiente a esta guía:

Añadir un susurro de llamada a una llamada entrante para comunicar algunos detalles sobre la llamada entrante a la llamada saliente antes de conectar ambas.
Entrada de blog en la que se explica cómo Conecta tu servidor de desarrollo local a la API de Vonage mediante un túnel ngrok.
El Referencia de Webhooks para Voice muestra los detalles de los webhooks entrantes para ambos answer_url y event_url puntos finales.
Consulte el Documentación de la OCNC para obtener más información sobre otras acciones que puedes utilizar para controlar el flujo de tus llamadas de Vonage.