Ending a Call or Canceling a Scheduled 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 end a synchronous call initiated in a previous tutorial. For simplicity’s sake, we’ll end the call by sending a DELETE request, specifying the resource ID of the phone call. You could also end the same call by sending a PUT request, using the hangup command.

Note that you can use the steps in this tutorial to cancel a scheduled call as well.

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 build a DELETE request to the /calls service, specifying the resource ID of the call you want to end or cancel. Structure the request URL as follows:

'https://v1.api.phone.com/calls/<resource ID>'

When you send the DELETE request, the Phone.com /calls service will locate the call and end or cancel it.

Sending the Request

Now that you’ve prepared the URL, 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>';

Now, add the cURL code to send your DELETE 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, "DELETE");
  curl_setopt($ch, CURLOPT_HEADER, true);
  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) {
      echo "Success! Call has been ended/canceled.\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 a JSON object containing information about your call. 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.

You now have all the components you need to make a successful DELETE request to /calls and end or cancel 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 code sample below in a web browser will end or cancel your call. Your browser will also display a message: Success! Call has been ended/canceled.

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>';

  $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, "DELETE");
  curl_setopt($ch, CURLOPT_HEADER, true);
  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) {
      echo "Success! Call has been ended/canceled.\n";
  } else {
      $error = array('http_code' => $info['http_code'], 'response' => $result);
      echo "We received an error: " . $error['response'] . "\n";
  }

  ?>

Learn More: