Make outbound calls

The workflow to make a Call using the Voice API is:

Outbound call workflow

  1. You make an authenticated Call request to the Voice API.
  2. Nexmo accepts the request and sends response information.
  3. Nexmo places a call and awaits an answer.
  4. On answer, Nexmo makes a GET request to retrieve an NCCO from your answer_url webhook endpoint and follows the actions in your NCCO.
  5. Nexmo sends a POST request to your event_url webhook endpoint when the Call status changes.

For more advanced systems, depending on the input from your user, you can return an NCCO to customize their experience.

To create a Call using the Voice API:

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

    [
      {
        "action": "talk",
        "voiceName": "Russell",
        "text": "Hi, this is Russell. You are listening to a Call made with Voice API"
      }
    ]
    

    To run a few tests without creating an NCCO provider in the next step, use the following static NCCOs:

  3. Create the webhook endpoint that provides an NCCO:

    <?php
    
    $method = $_SERVER['REQUEST_METHOD'];
    
    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
    
        //For more advanced Conversations you use the paramaters to personalize the NCCO
        //Dynamically create the NCCO to run a conversation from your virtual number
        if( $to == "441632960960")
          $ncco='[
          {
            "action": "talk",
            "text": "Hello Russell, welcome to a Call made with Voice API"
          }
          ]';
        else
          $ncco='[
          {
            "action": "talk",
            "text": "Hello Rebekka, welcome to a Call made with Voice API"
          }
          ]';
    
        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. Write a method to generate the JWT used to access Nexmo API for your application:

    <?php
    //This example uses a PHP library from composer require lcobucci/jwt.
    //To install: composer require lcobucci/jwt
    
    require __DIR__ . '/vendor/autoload.php';
    
    use Lcobucci\JWT\Builder;
    use Lcobucci\JWT\Signer\Key;
    use Lcobucci\JWT\Signer\Rsa\Sha256;
    
    function generate_jwt( $application_id, $keyfile) {
    
        $jwt = false;
        date_default_timezone_set('UTC');    //Set the time for UTC + 0
        $key = file_get_contents($keyfile);  //Retrieve your private key
        $signer = new Sha256();
        $privateKey = new Key($key);
    
        $jwt = (new Builder())->setIssuedAt(time() - date('Z')) // Time token was generated in UTC+0
            ->set('application_id', $application_id) // ID for the application you are working with
            ->setId( base64_encode( mt_rand (  )), true)
            ->sign($signer,  $privateKey) // Create a signature using your private key
            ->getToken(); // Retrieves the JWT
    
        return $jwt;
    }
    

    Note: after you have generated a jwt, it is valid for 24 hours.

  6. Use the Voice API to create your Call:

    <?php
    
    include 'application_generate_jwt.php';
    
    //Connection information
    $base_url = 'https://api.nexmo.com' ;
    $version = '/v1';
    $action = '/calls';
    
    //User and application information
    $application_id = "id-for-your-voice-application";
    
    //Mint your JWT
    $keyfile="application_secret_key.txt";
    
    $jwt = generate_jwt($application_id, $keyfile);
    
    //Add the JWT to the request headers
    $headers =  array('Content-Type: application/json', "Authorization: Bearer " . $jwt ) ;
    
    //Change the to parameter to the number you want to call
    $payload = '{
        "to":[{
            "type": "phone",
            "number": "441632960961"
        }],
        "from": {
            "type": "phone",
            "number": "441632960960"
        },
        "answer_url": ["https://nexmo-community.github.io/ncco-examples/first_call_talk.json"]
    }';
    
    //Create the request
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $base_url . $version . $action);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    
    $response = curl_exec($ch);
    
    echo $response;