Simple IVR (Interactive Voice Response)

To provide users with self-service capabilities or help them get relevant support faster, you may want to build an Interactive Voice Response (IVR) application. This guide shows how to do a basic IVR with keypad input (DTMF). For more advanced IVR leveraging speech input (Speech-to-Text), check the next guide, Advanced IVR.

Quick Start

You can use the Code Hub Interactive Voice Response (IVR) template to have the sample application working without worrying about installing tools and dependencies. Watch this short video to learn how and follow Code Hub template instructions for a quick start.

Setting Up for IVR

In order to work through this guide you need:

• A Vonage account.
• The Vonage CLI installed and set up.
• A publicly accessible web server so that Vonage can make webhook requests to your app, or for local development we recommend ngrok.
• The code, either clone the repository or download and extract the zip file to your machine.
• Learn how to use ngrok

Install Dependencies

Install the express web application framework and body-parser packages:

Create a Voice application

Use the CLI to create a Voice API application with the webhooks that will be responsible for answering a call on your Vonage number (/webhooks/voice/answer) and logging call events (/webhooks/voice/event), respectively.

These webhooks need to be accessible by Vonage's servers, so in this guide you will use ngrok to expose your local development environment to the public Internet. This article explains how to install and run ngrok and configure Vonage to send requests.

If you do not have an application, you can create one using the CLI

The command returns an application ID (which you should make a note of) and your private key information (which you can safely ignore for the purposes of this guide).

Run ngrok using the following command:

Make a note of the temporary host name that ngrok provides and use it in place of example.com in the following command:

Buy a phone number

To handle inbound calls to your application, you need a number from Vonage. If you already have a number to use, jump to the next section to associate the existing number with your application.

You can use the Vonage CLI to buy the phone number:

Search for a Number

You can purchase a number using the Vonage CLI. The following command searches for a number a purchase (specify an alternate two-character country code to purchase a number in another country).

Purchase a number

Once you have found a number you are satisfied with, you can purchase that using the vonage numbers buy command:

Link number to your application

Once you have a suitable number you can link it with your Vonage application run this command

The parameters are the phone number you want to use and the UUID returned when you created a voice application earlier.

Handle an Inbound Call

When Vonage receives an inbound call to your Vonage number it makes a request to the event webhook endpoint you set when you created a Voice application. A webhook is also sent each time DTMF input is collected from the user.

YOUR_URL/answer route should accept an HTTP

Your NCCO should use the talk action to greet the caller, and the input action to start listening to DTMF commands:

app.get('/webhooks/voice/answer', (req, res) => {
  const ncco = [
    {
      action: 'talk',
      bargeIn: true,
      text: 'Hello. Please enter a digit.'
    },
    {
      action: 'input',
      dtmf: {
        maxDigits: 1,
        timeout: 10
      }
    }
  ];

  res.json(ncco)
})

Handle Events

Vonage makes a

app.post('/webhooks/voice/event', (req, res) => {
  if (req.body.dtmf) {
    const ncco = [{
      action: 'talk',
      text: `You pressed ${req.body.dtmf.digits}`
    },
    {
      action: 'input',
      dtmf: {
        maxDigits: 1,
        timeout: 10
      }
    }];
  
    res.json(ncco);
    return
  } 
  
  console.log(req.body);
  res.send(200);
});

Create your Node.js Server

Finally, write the code to instantiate your Node.js server:

const port = 3000
app.listen(port, () => console.log(`Listening on port ${port}`))

Test Your Application

1. Run your Node.js application by executing the following command:

2. Call your Vonage number and listen to the welcome message.
3. Press a digit with the keypad.
4. Hear the digit you pressed back.

Next Steps

Here are a few more resources that could be useful for building this type of application:

• Interactive Voice Response (IVR) Code Hub template.
• Text-To-Speech Guide - includes the different voices on offer and information about SSML (Speech Synthesis Markup Language) for better control of the spoken output.
• Advanced IVR guide to learn how to capture speech input.
• AI studio documentation to learn how to build bots with a visual call flow editor.