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

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;