Welcome to Nexmo Developer

We are improving our Documentation, API references, learning resources & tooling to help you more effectively use our services. We want to help you find everything you need to integrate Nexmo APIs into your code.

As we start this transition, we’d love to hear from you with thoughts & suggestions. If you’ve got something, positive or negative, to tell us, please tell us using the feedback tool at the bottom of each guide or file an issue on GitHub. - Nexmo

Interactive Voice Response (IVR)

With the Voice API you easily create an IVR by generating NCCOs in a webhook.

Interactive Voice Response (IVR) is a technology that allows a computer to interact with humans through the use of voice and DTMF tones input on the handset keypad. You create IVR systems for mobile purchases, banking payments and services, retail orders, utilities, travel information and weather conditions.

In this section you will see how to build an IVR system using Nexmo APIs:

Prerequisites

To follow the steps in this tutorial you need to:

  • Setup a Nexmo account
  • Rent a virtual number using Dashboard or Developer API and set the webhook endpoint to your app
  • Create an application and associate it with your virtual number. Nexmo retrieves the initial NCCO from the answer_url webhook and sends the dtmf input to the eventUrl webhook defined in the initial NCCO

Create your IVR

In an IVR, when your user calls your virtual number you first send welcome message using text-to-speech or an audio stream. This message tells your user which button to push for your available services. Then, in function of the dtmf input, you generate the NCCOS that create a customized experience for your user.

Using bargeIn, your user does not have to listen to the whole announcement. If he or she already knows the choices, when they press an option during a talk or stream action, the announcement is stopped and the IVR executes their instruction. BargeIn makes the talk or stream actions asynchronous. You must set an input action later in the NCCO stack.

The workflow for an IVR is:

Participant answer_url Participant eventUrl Participant Nexmo Participant User User->Nexmo: Call virtual number Nexmo->answer_url: Send call info answer_url->Nexmo: Return NCCO with options\n Set eventUrl Nexmo->User: Send welcome message set in NCCO User->Nexmo: Press digits in function of welcome message Nexmo->eventUrl: Send dtmf input eventUrl->Nexmo: Send customized NCCO\n in function of dtmf input Note over Nexmo: Execute actions in NCCO Nexmo->User: Customized user experience

To implement this workflow:

  1. Supply your users with a virtual number to contact.

  2. When a user calls the virtual numbers, Nexmo forwards information about the Call to your webhook endpoint.

  3. At the webhook endpoint, store the caller information and send an NCCO with the welcome message and options:

    <?php
    
    $method = $_SERVER['REQUEST_METHOD'];
    $request = array_merge($_GET, $_POST);
    
    $ncco = "";
    switch ($method) {
      case 'GET':
        //Retrieve with the parameters in this request
        $to = $request['to']; //The endpoint being called
        $from = $request['from']; //The endpoint you are calling from
        $uuid = $request['conversation_uuid']; //The unique ID for this Call
        //Store the parameters in your database to identify this conversation in further interactions
    
        //Generate the welcome message
        $ncco='[
          {
            "action": "talk",
            "text": "Welcome to a Voice API I V R. Press 1 for maybe and 2 for not sure followed by the hash key",
            "voiceName": "Amy"
          },
          {
            "action": "input",
            "submitOnHash": "true",
            "eventUrl": ["https://example.com/ivr"]
          }
        ]';
        header('Content-Type: application/json');
        echo $ncco;
        break;
      default:
        //Handle your errors
        handle_error($request);
        break;
    }
    

  4. Your user hears the welcome message and presses a key to choose an option.

  5. Your code at the eventUrl webhook endpoint returns a customized NCCO in function of the keys pressed by your user:

    <?php
    /*
     *  Place this script at event_url for your Nexmo application
     */
    $method = $_SERVER['REQUEST_METHOD'];
    // work with get or post
    $request = array_merge($_GET, $_POST);
    
    /*
     *  Do something for changed call status
    */
    function handle_call_status()
    {
      $decoded_request = json_decode(file_get_contents('php://input'), true);
      // Set a default message for incorrect key presses
      $ncco = "";
      if (isset($decoded_request['dtmf'])) {
        switch ($decoded_request['dtmf']) {
          case '1':
              $ncco = '[
                  {
                    "action": "talk",
                    "text": "Thank you, I will forward you to the maybe department",
                    "voiceName": "Amy"
                  },
                  {
                    "action": "connect",
                    "eventUrl": ["https://example.com/events"],
                    "from": "441632960960",
                    "endpoint": [
                      {
                        "type": "phone",
                        "number": "441632960961"
                      }
                    ]
                  }
                ]';
              break;
          case '2':
          $ncco = '[
              {
                "action": "talk",
                "text": "Thank you, I will forward you to the not sure department",
                "voiceName": "Amy"
              },
              {
                "action": "connect",
                "eventUrl": ["https://example.com/events"],
                "from": "441632960960",
                "endpoint": [
                  {
                    "type": "phone",
                    "number": "441632960962"
                  }
                ]
              }
            ]';
              break;
          default:
            $ncco = '[
                {
                  "action": "talk",
                  "text": "I am sorry, I did not catch that. Please press 1 for maybe and 2 for not sure followed by the hash key",
                  "voiceName": "Amy"
                },
                {
                  "action": "input",
                  "submitOnHash": "true",
                  "eventUrl": ["https://example.com/ivr"]
                }
              ]';
              break;
      }
          return $ncco;
      }
    }
    
    /*
     *  Handle errors
    */
    function handle_error($request){
         //code to handle your errors
    }
    
    /*
      Send the 200 OK to Nexmo and handle changes to the call
    */
    switch ($method) {
      case 'POST':
        //Retrieve your dynamically generated NCCO.
        $ncco = handle_call_status();
        header('Content-Type: application/json');
        echo $ncco;
        break;
      default:
        //Handle your errors
        handle_error($request);
        break;
    }
    

And that's it. You have built an IVR. To do this you have provisioned and configured a virtual number, sent a generic welcome message, handled inbound calls and created a customized experience for your user.