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

Accept inbound calls

An inbound call is when a single person calls the virtual number associated with your Voice app.

The workflow for incoming calls is:

Inbound call workflow

  1. A user calls the virtual number associated with your application.
  2. Nexmo retrieves the NCCO from your answer_url webhook endpoint.
  3. Nexmo follows the actions in your NCCO.
  4. Nexmo sends status information to your webhook endpoint at event_url.

To handle inbound calls with the Voice API:

  1. Create a Nexmo application.

    Note: answer_url in the application you created points to a static Conversation NCCO.

  2. Create the NCCOs for the business logic you are implementing in your Voice app:

    [
        {
            "action": "connect",
            "eventUrl": ["https://example.com/events"],
            "from": "447700900000",
            "endpoint": [
              {
                "type": "phone",
                "number": "447700900001"
              }
            ]
        }
    ]
    

  3. Create the webhook that returns the NCCO for your Conversation. The code examples show how to create a private communication system where you connect an inbound call to a hidden outbound phone number:

    Note: You must serve the NCCO with a Content-Type header of application/json or text/plain

    <?php
    
    $method = $_SERVER['REQUEST_METHOD'];
    
    $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
    
        //Dynamically create the NCCO to connect the inbound call from a mapped virtual number to
        //a phone number
        if( $to == "441632960960")
          $ncco='[
            {
            "action": "connect",
            "eventUrl": ["https://example.com/events"],
            "from": "441632960960",
            "endpoint": [
              {
                "type": "phone",
                "number": "441632960961"
              }
            ]
          }
        ]';
        else
          $ncco='[
            {
            "action": "connect",
            "eventUrl": ["https://example.com/events"],
            "from": "441632960963",
            "endpoint": [
              {
                "type": "phone",
                "number": "441632960965"
              }
            ]
          }
          ]';
        header('Content-Type: application/json');
        echo $ncco;
        break;
      default:
        //Handle your errors
        handle_error($request);
        break;
    }
    

  4. Handle the call state changes at event_url. To inspect and debug state changes without writing your own server, create an online endpoint service such as requestb.in  or https://hookbin.com/  . The following code examples show you how to handle changes in Conversation state:

    <?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);
      // Work with the call status
      if (isset($decoded_request['status'])) {
        switch ($decoded_request['status']) {
          case 'ringing':
              echo("Handle conversation_uuid, this return parameter identifies the Conversation");
              break;
          case 'answered':
              echo("You use the uuid returned here for all API requests on individual calls");
              break;
          case 'complete':
              //if you set eventUrl in your NCCO. The recording download URL
              //is returned in recording_url. It has the following format
              //https://api.nexmo.com/media/download?id=52343cf0-342c-45b3-a23b-ca6ccfe234b0
              //Make a GET request to this URL using a JWT as authentication to download
              //the Recording. For more information, see Recordings.
              break;
          default:
              break;
      }
          return;
      }
    }
    
    /*
     *  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("HTTP/1.1 200 OK");
        break;
      default:
        //Handle your errors
        handle_error($request);
        break;
    }
    

  5. Your Conversation starts when somebody calls the virtual number associated with the application.