Canceling an SMS Blast

The Phone.com API includes an /sms service to send and receive SMS messages. Messages can be sent in real time or scheduled for delivery on a date and time of your choosing.

In this tutorial we will go through the steps required to cancel a scheduled SMS blast—a blast being a batch of multi-recipient SMS messages. If you need a reminder on how to schedule a blast, please see POST /sms.

In This Tutorial:

Prerequisites

To complete this tutorial, you will need:

  • A Phone.com API Developer account
  • Your application’s API key and password
  • A user agent capable of issuing an HTTP DELETE operation

Note that the Phone.com API can send an SMS to any U.S., Canada or UK telephone number. The Caller ID must match one of the phone numbers assigned to your account but cannot be a toll-free number. If you currently don’t have a number that is not toll free, you will need to add a number.

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

Preparing Your Request

Since this is a simple HTTP DELETE command, there is little to prepare for your request. We will simply utilize cURL in PHP as a user agent, and make our request against the Phone.com API. Note that you can use any user agent to make the request, as long as it supports making an HTTP DELETE request, Basic authentication, and SSL.

Also note that if there are no scheduled SMS messages in your account with the batch ID (batch_id) that you’re targeting, this request will return an error status, because you are issuing a command on a batch that does not exist in your account. Please follow the instructions for scheduling an SMS message to multiple recipients using a POST /sms request, so that your account will have scheduled messages to cancel.

When you send the DELETE request to the Phone.com /sms service, our system will find and retrieve all SMS messages that belong to the batch_id that you specify in your DELETE request. For a full list of SMS parameters that can be defined for this request, see DELETE /sms.

Sending the Request

In this tutorial, we’ll build our request using PHP, but you can use any language or library 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, the batch ID for the SMS messages we wish to cancel, and provide the API Key and API Password configured for your application.


  <?php

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

Then, we just give cURL the required options for a simple DELETE, with Basic authentication:


  $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");

  // set headers and method
  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. We will also make use of the returned HTTP status code, which we set to the $info variable above. This allows us to take conditional action depending on the response the Phone.com API returns.


  if($info == 200 || $info == 201) {
     $response = json_decode($result, true);
     $result = $response['results']['data'];
     echo "SMS blast successfully cancelled!\n" if $result;
  } else {
     $error = array('http_code' => $info['http_code'], 'response' => $result);
     echo "Error: $info['http_code']\n";
     echo "Response body: $result\n";
  }

  ?>

Note that a successful response will return an HTTP 200 OK code and a true value for the data result. 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 sample response would be:


  {
  "results" : {
      "data" : "1"
    }
  }

You now have all the components you need to make a successful DELETE request to /sms and delete your SMS blast. 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 delete your scheduled SMS blast, and display a success message.

Copy the Code

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


  <?php

  $batch_id = '<batch id>';
  $url     = 'https://v1.api.phone.com/sms/';
  $app_key = '<my app key>';
  $app_pwd = '<my 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");

  // set headers and method
  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 || $info == 201) {
     $response = json_decode($result, true);
     $result = $response['results']['data'];
     echo "SMS blast successfully cancelled!\n" if $result;
  } else {
     $error = array('http_code' => $info['http_code'], 'response' => $result);
     echo "Error: $info['http_code']\n";
     echo "Response body: $result\n";
  }

  ?>

Learn More: