Retrieving Received SMS Messages

The Phone.com API includes an /sms service to send and receive SMS messages. In this tutorial we will go through the steps required to do a GET request to retrieve a list of your receieved SMS messages.

In This Tutorial:

Prerequisites

To complete this tutorial, you will need:

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 GET 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 GET request, Basic authentication, and SSL.

Also note that if there are no SMS messages in your account for the phone number that you’re targeting, this request will return an empty results dataset. Please follow the instructions for sending an SMS message using an API request, or simply send a few messages from another phone, so that your account will have some data to return.

When you send your GET request to the Phone.com API /sms service, our system will retrieve all SMS messages in your account for the phone number that you specify. For a full list of SMS parameters that can be defined for this request, see API Resource: /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, and provide the API Key and API Password configured for your application.


  <?php

  $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 GET, 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");
  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);
      $sms_id = $response['results']['data'][0]['resource_id'];
      echo "ID: $sms_id\n";
  } 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 include your SMS messages as shown in the sample below. 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:


  {
     "response" : {
        "data" : {
          "to": "+15555551235",
          "from": "+15551231234",
          "message": "Welcome to Phone.com",
          "status": "sent",
          "type": "incoming",
          "application_id": "fe02e19d-cd54-11e2-bf99-91e4d3e209c1",
          "created_date": "2014-01-01T23:00:37",
          "created_epoch": 1382655637,
          "resource_id": "18a349a6-3d00-11e3-8779-91e7f37d368b",
          "url": "http://yourapplication.com/sms",
          "backup_url": "http://yourapplication2.com/sms",
          "voip_id": 0
   }
     }
   }

You now have all the components you need to make a successful GET request to /sms and view your SMS messages. 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 (configured for PHP) will retrieve your SMS messages. Using command-line PHP will also work.

Success! You’re now able to retrieve any SMS messages sent to your Phone.com managed numbers. The next step from here, is to write an application that receives an SMS callback. This will allow Phone.com to push all new SMS messages to your app, allowing you to use that data however you choose. For example, imagine writing an SMS voting app that manages SMS answers to a text-based user poll.

Copy the Code

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


  <?php

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

  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);
     echo $response;
  } else {
     $error = array('http_code' => $info['http_code'], 'response' => $result);
     echo "Error: $info['http_code']\n";
     echo "Response body: $result\n";
  }

  ?>

A sample response is shown below:


  {
    "response" : [
      {
       "to": "+15555551235",
       "from": "+15551231234",
       "message": "Welcome to Phone.com",
       "status": "sent",
       "type": "incoming",
       "application_id": "fe02e19d-cd54-11e2-bf99-91e4d3e209c1",
       "created_date": "2014-01-01T23:00:37",
       "created_epoch": 1382655637,
       "resource_id": "18a349a6-3d00-11e3-8779-91e7f37d368b",
       "url": "http://yourapplication.com/sms",
       "backup_url": "http://yourapplication2.com/sms",
       "voip_id": 0
      }
   }

Learn More: