Cómo enviar notificaciones de voz

Una llamada telefónica es un método de alta prioridad para enviar alertas críticas. En esta guía, aprenderá a automatizar las notificaciones de voz a una lista de destinatarios, reproducir un mensaje personalizado y capturar la confirmación del usuario a través de la entrada del teclado (DTMF).

Requisitos previos

• A Account de Vonage
• Node.js instalado en su máquina.
• ngrok instalado en su máquina.

Inicializar la carpeta del proyecto

1. Cree el entorno en el que vivirán su código y sus claves de seguridad.
2. Abra su terminal y cree un nuevo directorio:

3. Inicializa el proyecto e instala Vonage SDK y Express:

Exponga su servidor local

Vonage needs to send webhooks to your local machine. Use ngrok to expose your server:

ngrok will forward your local port 3000 to a public URL like https://{random-id}.ngrok.app.

Copy this URL. You’ll need it when configuring your Vonage application in the next step.

Crear una aplicación de Vonage

Genera tus credenciales a través del Panel de control y guárdalas en la carpeta que acabas de crear.

1. Inicia sesión en el panel de Vonage.

2. Ir a Applications > Crear una nueva aplicación.

3. Autentificación: Haga clic en Generar claves públicas y privadas.

   • Un archivo denominado private.key se descargará.
   • Mueve esto private.key de la carpeta Descargas en su voice-notifications carpeta.

4. Capacidades: Activar Voz.

5. En los ajustes de Voz, configure los siguientes webhooks:

   • URL de respuesta: https://{random-id}.ngrok.app/answer (Método:
     GET
     )
   • URL del evento: https://{random-id}.ngrok.app/event (Método:
     POST
     )

6. Haga clic en Guardar cambios en la parte inferior.

Crear el servidor Webhook (server.js)

Cuando Vonage contesta una llamada, obtiene un Objeto de control de llamada (NCCO) de su answer_url. Este array JSON define el "script" que sigue la llamada. Crea un archivo llamado server.js y configurar el webhook para proporcionar la OCNC:

const express = require('express');
const app = express();
app.use(express.json());

app.get('/answer', (req, res) => {
  // NCCO defines what the recipient hears
  res.json([
    {
      action: 'talk',
      text: 'This is a priority notification. Please press 1 to confirm receipt.'
    },
    {
      action: 'input',
      type: [ 'dtmf' ],
      dtmf: { maxDigits: 1 }
    }
  ]);
});

app.post('/event', (req, res) => {
  // Capture the button press
  if (req.body.dtmf && req.body.dtmf.digits === '1') {
    console.log(`✅ Confirmation received from UUID: ${req.body.uuid}`);
  }
 if (status) {
    console.log(`Call Status Update: ${status} (UUID: ${req.body.uuid})`);
  }
  res.status(204).send();
});

app.listen(3000, () => console.log('🚀 Webhook server listening on port 3000'));

Crear el script de difusión (broadcast.js)

Cree un archivo llamado broadcast.js. Este script activa las llamadas salientes.

const { Vonage } = require('@vonage/server-sdk');

// --- 1. CONFIGURATION ---
const API_KEY = "YOUR_API_KEY";
const API_SECRET = "YOUR_API_SECRET";
const APP_ID = "YOUR_APP_ID";
const VONAGE_NUMBER = "YOUR_VONAGE_NUMBER";
const TUNNEL_URL = "https://{random-id}.ngrok.app" // From the ngrok step above

// --- 2. PLACEHOLDER PROTECTION ---
const config = { API_KEY, API_SECRET, APP_ID, VONAGE_NUMBER, TUNNEL_URL };
Object.keys(config).forEach(key => {
    if (config[key].includes("YOUR")) {
        console.error(`❌ ERROR: The ${key} placeholder has not been updated!`);
        process.exit(1);
    }
});

const vonage = new Vonage({
  apiKey: API_KEY,
  apiSecret: API_SECRET,
  applicationId: APP_ID,
  privateKey: './private.key'
});

const recipients = [
  { name: 'Alice', number: '15551234567' }
];

async function broadcast() {
  for (const person of recipients) {
    try {
      const result = await vonage.voice.createOutboundCall({
        to: [{ type: 'phone', number: person.number }],
        from: { type: 'phone', number: VONAGE_NUMBER },
        answer_url: [`${TUNNEL_URL}/answer`],
        event_url: [`${TUNNEL_URL}/event`]
      });
      console.log(`☎️  Calling ${person.name}... (UUID: ${result.uuid})`);
    } catch (err) {
      console.error(`❌ Failed to call ${person.name}:`, err.message);
    }
  }
}

broadcast();

Pruebe su notificación

1. Inicie su servidor: Ejecute node server.js en la carpeta del proyecto.
2. Inicie la emisión: En otro terminal, ejecute node broadcast.js. Su teléfono sonará, reproducirá el mensaje y registrará su confirmación en la consola cuando pulse "1".

Próximos pasos

Personalización: Cambia texto a voz voz o utilizar el flujo en tu OCN para reproducir archivos MP3 pregrabados en lugar de texto a voz.

Voz AI: Escuche la respuesta del destinatario con voz a texto o conectar un bot de voz con WebSocket.

Contestadores automáticos: Utilice detección de contestadores automáticos para dejar un mensaje de voz.

Escalabilidad: Para listas grandes, implanta un sistema de colas que respete Vonage Límites de tarifa.