Sending an SMS Message

The Phone.com API includes an /sms service to send and receive SMS messages. Messages can be sent in real time or scheduled. In this tutorial we will go through the steps required to send an SMS message to your SMS-enabled phone.

In This Tutorial:

Prerequisites

To complete this tutorial, you will need:

Note that SMS messages can be sent to any U.S. or Canada number, and sent from any U.S. or Canada number. Toll-free or global/international numbers are not supported in either direction for the /sms service.

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

First, we will construct the JSON object for your SMS message as follows:


 {
    "from": "<caller ID>",
    "to": "<caller ID>",
    "message": "This is a test of the Phone.com API SMS Service."
 }

Parameters:

  • from: The phone number from which you will send the message. Note that the number must be written using the E.164 format, e.g. +15551234567.
  • to: The phone number to which you will send the message.
  • message: A text message. See the reference for restrictions on the length of the message.

When you send this JSON object to the Phone.com API using a POST request to the /sms service, our system will forward the SMS message to your phone carrier immediately. For a full list of SMS parameters that can be defined in the object, see POST /sms.

Sending the Request

Now that you’ve prepared the JSON object containing your SMS message text, 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/sms/';
  $app_key = '<my app key>';
  $app_pwd = '<my app password>';

Then, add the JSON object with your text message:


  $payload = <<<JSON
   {
      "from": "<caller ID>",
      "to": "<caller ID>",
      "message": "This is a test of the Phone.com API SMS Service."
   }
  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);
      $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 the resource ID (UUID) for your new greeting, 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 sample response would be:


  {
     "response" : {
        "results" : "85c94fdd-ab89-11e2-b773-8206ab1f72e1"
     }
  }

You now have all the components you need to make a successful POST request to /sms and send your SMS message. 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 send your SMS message. Typically, you will receive the SMS message within seconds of sending the REST request, so check the phone to which you sent the message. If your device is currently roaming, it might take several minutes for the message to reach its current network.

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.

Congratulations! You’ve sent an SMS message using the Phone.com API.

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

  $payload = <<<JSON
   {
      "from": "<caller ID>",
      "to": "<caller ID>",
      "message": "This is a test of the Phone.com API SMS Service."
   }
  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);
      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": "+5551231234",
          "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": 64783
       }
  }

Learn More: