Playing Audio on 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 play an audio recording on a synchronous call.

In This Tutorial:


Prerequisites

To complete this tutorial, you will need:

  • A Phone.com API Developer account
  • Your application’s API key and API password
  • The resource ID of a currently connected Phone.com call. See Placing a Phone Call.
  • The resource ID of a media resource you want to play on the call.

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": [
        {
            "play": {
                "resource_id": "<resource ID for the audio file>"
            }
        }
    ]
}


Parameters:

  • commands: The PUT method for /calls accepts an array of call commands, and for this tutorial we will use the command play. This command includes all the information needed to play an audio file on the call:
    • resource_id: The resource ID for the media file to be played

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

Sending the Request

Now that you’ve prepared the JSON object containing your play 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

  $call_id = '<resource ID for the call>';
  $url     = 'https://v1.api.phone.com/calls/' . $call_id;
  $app_key = '<your app key>';
  $app_pwd = '<your app password>';

Then, add the JSON object:


  $payload = <<<JSON
  {
      "commands": [
          {
              "play": {
                  "resource_id": "<resource ID for the audio file>"
              }
          }
      ]
  }
  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_CUSTOMREQUEST, "PUT");
  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) {
      $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 play command was accepted by call id: $call_id\n";
      } else {
          echo "The audio resource was not played 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": "12345678900",
                  "from": "12345678901",
                  "duration": 17,
                  "direction": "outbound",
                  "schedule_start": "2014-01-03T05:17:27",
                  "schedule_start_epoch": 1388726247,
                  "schedule_expire": "2014-01-03T05:32:27",
                  "schedule_expire_epoch": 1388727147,
                  "time_start": "2014-01-03T05:17:29",
                  "time_start_epoch": 1388726249,
                  "status": "ready"
          },
          "commands": [
              {
                  "command": "play",
                  "resource_id": "94f9e282-6e7b-409e-a7bf-875555555555",
                  "status": 200,
                  "result": "ok"
              }
          ]
      }
  }

You now have all the components you need to make a successful PUT request to /calls and play an audio file on your 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 Copy the Code sample below in a web browser will play the audio file on your call. Your browser will also display a success message: Success! The play command was accepted by call id: e980d823-f587-11e2-a026-eb13f7ef552c

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

Success! You’ve played an audio file on a phone call using the /calls service. You can continue to interact with the call using additional PUT requests specifying the call’s resource ID, or you can use the DELETE method to end the call.

Copy the Code

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


  <?php

  $call_id = ‘<resource ID for the call>’;
  $url     = 'https://v1.api.phone.com/calls/' . $call_id;
  $app_key = '<your app key>';
  $app_pwd = '<your app password>';

  $payload = <<<JSON
  {
      "commands": [
          {
              "play": {
                  "resource_id": "<resource ID for the audio file>"
              }
          }
      ]
  }
  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_CUSTOMREQUEST, "PUT");
  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) {
      $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 play command was accepted by call id: $call_id\n";
      } else {
          echo "The audio resource was not played 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: