Scheduling a Call

Our /calls service will be available soon! Read about call features and functions below but please don't try them out just yet.

The Phone.com API’s /calls service allows you to make and interact with phone calls. Calls can be made in real time (synchronously or asynchronously), or scheduled for a future time.

In this tutorial, we will schedule a synchronous call, retrieve the resource ID of the call and check the status of the call before and after execution.

In This Tutorial:


Prerequisites

To complete this tutorial, you will need:

Before beginning this task, please refer to Systems and Requirements and the reference information for the /calls service. Also, the following topics show you how to structure requests to our API:


Preparing Your Call Request

First, we will construct the JSON object for your request to the /calls service. This should look familiar to you if you completed the Placing a Phone Call tutorial, with the addition of schedule_start and schedule_expire elements, which instruct the Phone.com API to schedule your commands for execution later.


{
   "commands": [
       {
           "dial": {
               "to": "<Phone number to be dialed>",
               "from": "<Your phone number>"
               "timeout": 20,
               "schedule_start": "2015-04-01T12:00:00-07:00",
               "schedule_end": "2015-04-05T12:30:00-07:00"
           },
           {
           "say": {
               "text": "Welcome to the Phone.com A P I"
           }
       }
       }
   ]
}


Parameters:

  • commands: The POST method for /calls accepts an array of call commands, and for this tutorial we will use the commands dial and say. The dial command includes all the information needed to connect a phone call:
    • to: The phone number to be dialed (E.164 format)
    • from: The phone number that will do the dialing (E.164 format)
    • timeout: The number of seconds for our service to wait for the call to connect. The call will end automatically after the time you set.
    • schedule_start: The time you want the call event to trigger (ISO 8601 format)
    • schedule_end: (Optional) In the event that our system cannot execute your call event, set this parameter to cancel the scheduled call after the time you set (ISO 8601 format)

The say command defines a text string that is converted to an audio message on the fly using the Phone.com Text to Greeting service.

When you send this JSON object to the Phone.com API using a POST request to the /calls service, the commands will be validated by our API server and stored for execution at the time defined in your schedule_start element. For a full list of parameters that can be defined in the object, see dial and say.

Sending the Request

Now that you’ve prepared the JSON object containing your dial and say commands, we can go ahead and build the API request. In this tutorial, we’ll build our request using PHP, but you can use any language that can make HTTPS requests. If you would prefer to make your request using cURL, see Making API Requests Using cURL.

At the beginning of the request, we need to define the URL for the Phone.com API, and provide the API Key and API Password configured for your application.


  <?php

  $url     = 'https://v1.api.phone.com/calls/';
  $app_key = '<my app key>';
  $app_pwd = '<my app password>';

Then, add the JSON object:


  $payload = <<<JSON
  {
     "commands": [
         {
             "dial": {
                 "to": "<Phone number to be dialed>",
                 "from": "<Your phone number>"
                 "timeout": 20,
                 "schedule_start": "2015-04-01T12:00:00-07:00",
                 "schedule_end": "2015-04-05T12:30:00-07:00"
             },
             {
             "say": {
                 "text": "Welcome to the Phone.com A P I"
             }
         }
         }
     ]
  }
  JSON;

And the cURL code to send your POST request:


  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);

  // authentication
  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, "$app_key:$app_pwd");

  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  $result = curl_exec($ch);
  $info = curl_getinfo($ch, CURLINFO_HTTP_CODE);

  curl_close($ch);

Finally, you will need to write code to parse the response sent back to your application by our API server.


  if($info == 200 || $info == 201) {
     $response = json_decode($result, true);
     $call_id = $response['results']['call']['resource_id'];
     $call_status = $response['results']['call']['status'];
     if( $call_status == 'ready' ) {
         echo "Success! The resource ID for your scheduled call is: $call_id\n";
     } else {
         echo "The call was not scheduled successfully, error: " . $response['commands'][0]['result'] . "\n";
     }
  } else {
     $error = array('http_code' => $info['http_code'], 'response' => $result);
     echo "We received an error: " . $error['response'] . "\n";
  }

  ?>

Note that a successful response will return an HTTP 200 OK code and include the resource ID (UUID) for your call object, which allows you to check on its status. An HTTP 4xx code would indicate a problem in your request, and an HTTP 5xx code would indicate a problem with the Phone.com API service.

A typical GET /calls response will include information about the call and the status of any commands you sent.


  {
     "response": {
         "service": "calls",
         "call": {
             "resource_id": "55bb5e92-7436-11e3-b573-d5e99f999999",
             "application_id": "4556e204-05de-11e3-bf32-cdee47777777",
             "to": "18008675309",
             "from": "11234567890",
             "duration": 9,
             "direction": "outbound",
             "schedule_start": "",
             "schedule_start_epoch": 0,
             "schedule_end": "",
             "schedule_end_epoch": 0,
             "time_start": "2014-01-03T05:17:29",
             "time_start_epoch": 1388726249,
             "status": "ready"
         },
         "commands": [
             {
                 "command": "dial",
                 "to": "+18008675309",
                 "from": "+11234567890"
                 "status": 200,
                 "result": "ok"
             },
             {
                 "command": "say",
                 "text": "Welcome to the Phone.com A P I",
                 "status": 200,
                 "result": "ok"
             }
         }
     ]
  }

You now have all the components you need to make a successful POST request to /calls and schedule your phone call. Use the code snippets we created above to make your request, or copy and use the full code sample below.

How Do I Know it Worked?

Running the code sample sample below in a web browser will schedule your call. Your browser will also display a success message: Success! The resource ID for your scheduled call is: e980d823-f587-11e2-a026-eb13f7ef552c

Using this UUID you can check the status of your scheduled call by issuing a GET request against the /calls service. The response object will indicate your call’s waiting state. Simply wait until the time you set in your schedule_start element, and your call will connect to its destination phone number and say your message.

Success! You have scheduled a phone call using our /calls service, retrieved the resource ID for it, and watched it execute successfully. You can now interact with the call–that is, you can do a PUT request to /calls using the resource ID, and send additional commands to the call. For example, you can play a greeting or require the callee to enter DTMF selections.

Copy the Code

The full set of PHP code for this tutorial is shown below.


  <?php

  $url     = 'https://v1.api.phone.com/calls/';
  $app_key = '<my app key>';
  $app_pwd = '<my app password>';

  $payload = <<<JSON
  {
     "commands": [
         {
             "dial": {
                 "to": "<Phone number to be dialed>",
                 "from": "<Your phone number>"
                 "timeout": 20,
                 "schedule_start": "2015-04-01T12:00:00-07:00",
                 "schedule_end": "2015-04-05T12:30:00-07:00"
             },
             {
             "say": {
                 "text": "Welcome to the Phone.com A P I"
             }
         }
         }
     ]
  }
  JSON;


  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);

  // authentication
  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, "$app_key:$app_pwd");

  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  $result = curl_exec($ch);
  $info = curl_getinfo($ch, CURLINFO_HTTP_CODE);

  curl_close($ch);

  if($info == 200 || $info == 201) {
     $response = json_decode($result, true);
     $call_id = $response['results']['call']['resource_id'];
     $call_status = $response['results']['call']['status'];
     if( $call_status == 'ready' ) {
         echo "Success! The resource ID for your scheduled call is: $call_id\n";
     } else {
         echo "The call was not scheduled successfully, error: " . $response['commands'][0]['result'] . "\n";
     }
  } else {
     $error = array('http_code' => $info['http_code'], 'response' => $result);
     echo "We received an error: " . $error['response'] . "\n";
  }

  ?>

Learn More: