Como enviar notificações de voz

Uma ligação telefônica é um método de alta prioridade para o envio de alertas críticos. Neste guia, você aprenderá como automatizar notificações de voz para uma lista de destinatários, reproduzir uma mensagem personalizada e obter a confirmação do usuário por meio de entradas no teclado (DTMF).

Pré-requisitos

• A Account da Vonage
• Node.js instalado no seu computador.
• ngrok instalado no seu computador.

Inicialize a pasta do seu projeto

1. Crie o ambiente onde seu código e suas chaves de segurança ficarão armazenados.
2. Abra o terminal e crie um novo diretório:

3. Inicialize o projeto e instale o SDK e o Express da Vonage:

Exponha seu servidor local

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

Criar uma aplicação da Vonage

Gere suas credenciais pelo Painel e salve-as na pasta que você acabou de criar.

1. Faça login no Painel de Controle da Vonage.

2. Acesse Applications > Criar um novo aplicativo.

3. Autenticação: Clique Gerar chaves públicas e privadas.

   • Um arquivo chamado private.key vai baixar.
   • Mova isso private.key arquivo da pasta “Downloads” para a sua voice-notifications pasta.

4. Recursos: Ativar voz.

5. Nas configurações do Voice, defina os seguintes webhooks:

   • URL da resposta: https://{random-id}.ngrok.app/answer (Método: GET)
   • URL do evento: https://{random-id}.ngrok.app/event (Método: POST)

6. Clique Salvar alterações na parte de baixo.

Criar o servidor de webhooks (server.js)

Quando a Vonage atende uma chamada, ela busca um Objeto de Controle de Chamadas (NCCO) do seu answer_url. Esse array JSON define o “script” que a chamada segue. Crie um arquivo chamado server.js e configurar o webhook para fornecer o NCCO:

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

Crie o script de transmissão (broadcast.js)

Crie um arquivo chamado broadcast.js. Esse script aciona as chamadas de saída.

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

Teste sua notificação

1. Inicie seu servidor: Execute node server.js na pasta do seu projeto.
2. Inicie a transmissão: em um terminal separado, execute node broadcast.js. Seu telefone tocará, reproduzirá a mensagem e registrará sua confirmação no console quando você pressionar “1”.

Próximos passos

Personalização: Alterar conversão de texto em fala falar ou usar o fluxo configure no seu NCCO para reproduzir arquivos MP3 pré-gravados em vez da função de conversão de texto em fala.

IA de voz: Ouça a resposta do destinatário com conversão de fala em texto ou conectar um bot de voz com WebSocket.

Secretárias eletrônicas: Uso detecção de secretária eletrônica para deixar uma mensagem na caixa postal.

Escalabilidade: Para listas grandes, implemente um sistema de fila para respeitar a Vonage Limites de taxa.