Placing a Phone 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 place a synchronous call, retrieve the resource ID of the call and check the status of the call.

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 as follows:


{
    "commands": [
        {
            "dial": {
                "to": "<Phone number to be dialed>",
                "from": "<Your phone number>",
                "timeout": 20
            }
        }
    ]
}


Parameters:

  • commands: The POST method for /calls accepts an array of call commands, and for this tutorial we will use the command dial. This 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 automatically end after the time you set.

When you send this JSON object to the Phone.com API using a POST request to the /calls service, the commands will be validated and processed by our API server, establishing the call. For a full list of parameters that can be defined in the object, see dial.

Sending the Request

Now that you’ve prepared the JSON object containing your dial command, 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
              }
          }
      ]
  }
  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 call is: $call_id\n";
      } else {
          echo "The call was not connected 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 /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_expire": "",
              "schedule_expire_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"
              }
          }
      ]
  }

You now have all the components you need to make a successful POST request to /calls and place 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 code sample sample below in a web browser will place your call. Your browser will also display a success message: Success! The ID for your call is: e980d823-f587-11e2-a026-eb13f7ef552c

You can also check the status of the message using our API’s /calls service, this time by retrieving the call resource with a GET request.

Success! You’ve placed a phone call using our /calls service and retrieved the resource ID for it. 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
              }
          }
      ]
  }
  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 call is: $call_id\n";
      } else {
          echo "The call was not connected 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: