How to Send Voice Notifications

A phone call is a high-priority method for delivering critical alerts. In this guide, you will learn how to automate voice notifications to a list of recipients, play a custom message, and capture user confirmation via keypad (DTMF) input.

Prerequisites

• A Vonage account
• Node.js installed on your machine.
• ngrok installed on your machine.

Initialize your Project Folder

1. Create the environment where your code and security keys will live.
2. Open your terminal and create a new directory:

3. Initialize the project and install the Vonage SDK and Express:

Expose Your Local Server

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

Create a Vonage Application

Generate your credentials via the Dashboard and save them to the folder you just created.

1. Log in to the Vonage Dashboard.

2. Go to Applications > Create a new application.

3. Authentication: Click Generate public and private keys.

   • A file named private.key will download.
   • Move this private.key file from your Downloads folder into your voice-notifications folder.

4. Capabilities: Enable Voice.

5. In the Voice settings, set the following webhooks:

   • Answer URL: https://{random-id}.ngrok.app/answer (Method:
     GET
     )
   • Event URL: https://{random-id}.ngrok.app/event (Method:
     POST
     )

6. Click Save Changes at the bottom.

Create the Webhook Server (server.js)

When Vonage answers a call, it fetches a Call Control Object (NCCO) from your answer_url. This JSON array defines the "script" the call follows. Create a file named server.js and set up the webhook to provide the 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'));

Create the Broadcast Script (broadcast.js)

Create a file named broadcast.js. This script triggers the outbound calls.

Test your Notification

1. Start your server: Run node server.js in your project folder.
2. Start the broadcast: In a separate terminal, run node broadcast.js. Your phone will ring, play the message, and log your confirmation to the console when you press "1".

Next Steps

Customization: Change text-to-speech voice or use the stream action in your NCCO to play pre-recorded MP3 files instead of text-to-speech.

Voice AI: Listen to the recipient answer with speech-to-text or connect a voice bot with WebSocket.

Answering Machines: Use answering machine detection to leave a voicemail message.

Scalability: For large lists, implement a queue system to respect Vonage Rate Limits.