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.

You can also create a simple or advanced IVR without any coding, with Vonage AI Studio using a visual call flow builder and TTS, STT and NLU features. Check the AI Studio documentation to learn more.

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:

npm install express body-parser

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

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

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:

ngrok http 3000

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

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

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).

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.

Purchase a number

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

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

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

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

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

GET
request and return a Nexmo Call Control Object (NCCO) that tells Vonage how to handle the call.

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

POST
request to this endpoint every time the call status changes. DTMF digits will be sent to the same route if you don’t provide a special event URL for input action, so let’s handle user input here:

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:
node index.js
  1. Call your Vonage number and listen to the welcome message.
  2. Press a digit with the keypad.
  3. Hear the digit you pressed back.

Next Steps

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