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'];
    $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
    
        //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.