API Resource: /sms

Want to get straight to work? Jump to available methods: POST /sms | GET /sms | DELETE /sms | GET /sms/UUID | PUT /sms/UUID | DELETE /sms/UUID


The Phone.com API /sms service lets you schedule, send and receive SMS messages. An SMS object could be an incoming application-bound SMS message, or an outgoing message, scheduled and sent from your app through one of your Phone.com numbers.

The illustration below shows how you might use SMS messaging to deliver text-based discounts on your products. First, a customer sends an SMS message to your Phone.com phone number to sign up for text-based discounts from your company. The message is routed through our API to your application, where it is processed, and the applicant becomes a subscriber in your database.


Overview of incoming SMS messaging

From then on, the subscriber will receive regular, scheduled outbound SMS discount-program messages from your application.


Overview of outgoing SMS messaging

Note: SMS messages sent through the Phone.com API have a character limit of 160 characters. The service will split longer messages on a 160-character boundary, up to a maximum of three messages. Characters that fall outside the total maximum of three 160-character messages will be discarded.

What Can I Do with /sms?

Phone.com’s standard phone service lets you send and receive SMS messages using your Phone.com numbers. The Phone.com API extends this functionality, letting you send SMS messages from your application (through your phone number and our API server) to your users. You can also direct incoming SMS messages from users to your application; schedule outgoing messages to send later; or configure your application to send SMS messages on the fly, triggered by user actions.

Use the Phone.com /sms service to do the following and more:

  • Send your clients customized information on new products and promotions
  • Use SMS to deliver appointment reminders, travel alerts, or real-time account notifications
  • Offer opt-in SMS coupons and discounts
  • Deliver emergency or crime alerts
  • Keep in touch with thank-yous for recent purchases or participation

SMS Settings in the Telephony Toolkit

SMS messages are sent either manually from your phone, or triggered based on actions or events in your application. For this reason, there are few SMS-related options in your Phone.com API Developer account settings.

Be sure, though, to set up the phone number you plan to use for your application, and note that you cannot receive or send SMS messages from toll-free phone numbers.

Also, if you want to route incoming SMS messages to your application, you will need to set up a webserver for your app, and make sure that SMS Forwarding is set to route SMS messages to your application. If you have already added a number, you can edit SMS-forwarding settings on the Edit Number page shown below (Configure > Manage Numbers > Edit).


SMS Forward setting on the Edit Number page

Working with the /sms API Resource

To build Phone.com SMS messaging into your application, you will need to invoke our SMS service. The right API request to /sms lets you send or schedule an SMS message, or retrieve or delete scheduled messages.

When an SMS object is created (POST), it is assigned a unique resource ID (UUID), which can then be used to retrieve, update, route or delete that object.

Each incoming or outgoing SMS message is linked to your Phone.com API Developer account number, your application’s API key (see Configuring Your Application), as well as the message’s unique resource ID. These IDs, which are generated automatically for each SMS object by our API service, are your key to accessing and managing the data and metadata associated with each object.

For more information, see Managing SMS Messages.

Note: The maximum size for media files or JSON objects included with a POST or PUT request to the Phone.com API is 20 MB.

POST /sms

Use POST /sms to generate a new outgoing SMS message. Note that you cannot send an SMS message from a toll-free number.

Example

POST https://v1.api.phone.com/sms

Authentication

This method requires authentication.

Request Body Fields and Example

Field Type Values Description
from String Formatted telephone number (E.164 format) Caller ID number to display on the outgoing SMS message. It must be a number associated with your Phone.com account. Example: +15555551234
to String Formatted telephone number (E.164 format) Outgoing destination number for the SMS message. Example: +15555551234
message String Alphanumeric, underscore, and common punctuation Text body of the outgoing SMS message. Max. 160 characters per message. Longer messages are split into a maximum of three 160-character messages on your behalf. Total max. size of this field is 480 chars.
schedule_start (Optional) Integer/String Epoch seconds or ISO 8601 Start time for a scheduled event. Example: 2015-01-01T10:36:00-07:00
schedule_expire (Optional) Integer/String Epoch seconds or ISO 8601 Expire time for a scheduled event. Example: 2015-01-01T10:36:00-07:00

Request Body Format Example

The example below shows how to send (POST) an SMS message to a specific phone number. Note that the schedule expiration date and time must be after the schedule start date and time.


{
  "from": "+15555551234",
  "to": "+15555552345",
  "message": "Insert SMS message here",
  "schedule_start": "2015-01-01T10:36:00-07:00",
  "schedule_expire": "2015-01-01T10:37:00-07:00"
}

Success Response

HTTP Code: 200 OK


{
  "response" : {
     "data" : {
        "resource_id" : "faf5a0fc-89d5-11e3-b75e-eec9a9528cda"
     }
  }
}

Error Response

  • HTTP Code: 404 Not Found (Dependent resource not found)
  • HTTP Code: 500 Internal Server Error

For HTTP Code 404:

{
  "response" : {
     "error" : {
        "code" : 30600,
        "info" : "The system could not locate the SMS you requested.",
        "url" : "https://docs.phone.com/refguides/errorref/serviceerrors.html#error-code-30600"
     }
  }
}

Sample POST /sms Request (PHP)


  <?php
  $url = "https://v1.api.phone.com/sms";

  $post_body = <<<SMSDATA
  {
    "from": "+15555551234",
    "to": "+15555551234",
    "message": "Insert SMS message here",
    "schedule_start": "2015-01-01T10:36:00-07:00",
    "schedule_expire": "2015-01-01T12:36:00-07:00"
  }
  SMSDATA;

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  // authentication
  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, "username:password");
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $post_body);
  curl_setopt($ch, CURLOPT_HEADER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER,
            array('Content-Type: application/json',
                      'Content-Length: ' . strlen($post_body))
             );
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  $result = curl_exec($ch);

  $info = curl_getinfo($ch);
  curl_close($ch);

  if($info['http_code'] == 200) {
    echo $result;
  } else {
    $error = array('http_code' => $info['http_code'], 'response' => $result);
    echo json_encode($error);
  }
  ?>

Back to Methods Available for /sms.


GET /sms

Use GET /sms to retrieve a list of existing SMS messages in your account—either incoming (application target) or outgoing. Note that, by default, you can retrieve a maximum of 20 SMS messages per request. You can increase the number of returned messages to a maximum of up to 50 by setting the limit parameter, and you can set offset to page through all available objects.

Example

GET https://v1.api.phone.com/sms

Authentication

This method requires authentication.

Parameters

Parameter Type Description
status (Optional) String Retrieve SMS messages matching a particular status. By default only new messages are returned. Valid statuses are: new and sent. Note that outbound and inbound messages have a default status of new until our API server either transmits your outbound message to the destination phone number, or an inbound SMS message is routed successfully to your application, at which point the status will change to sent.
limit (Optional) Integer Limits the result set to the value provided, to a maximum of 50 SMS messages. If you do not specify a limit, GET requests have a default maximum of 20 objects returned.
offset (Optional) Integer Skips the specified number of SMS objects. Used to control paginated results. Example: GET /sms?offset=10 will skip over the first ten results returned from the command, and start with the 11th.
sort (Optional) String By default, SMS objects are listed starting with the most recent object. Specifying the sort order as asc switches that order to start with the oldest object first. Specify desc to switch the order back to the default behavior. Example: GET /sms?sort=asc.

Success Response

HTTP Code: 200 OK

Response Body Fields and Example

Field Type Description
status String Indicates the state of your SMS objects
message String Body of the SMS messsage text
to String Specifies the phone number that will receive the SMS message
from String Specifies the phone number from which the SMS message will be sent (appears in the recipient’s caller ID)
resource_id UUID resource_id for a valid SMS object
voip_id Integer Your Phone.com API Developer account number
type String Indicates whether the SMS object is inbound or outbound
application_id String Your Phone.com API application key. This is the hexadecimal key that is automatically generated when you configure your application in your account.
batch_id UUID Resource ID of the batch to which the SMS object belongs. When no batch is present, the value is null.
created_date String Date string representing the UTC time that the object was created in the Phone.com API system. (ISO 8601 format)
created_epoch Integer Unix time stamp representing the UTC time that the object was created in the Phone.com API system. (Unix time format)

Response Body Format Example

Example of the response body format for GET /sms.

Example for: https://v1.api.phone.com/sms/?limit=5&offset=0


{
  "response" : {
     "data" : [
        {
           "resource_id" : "68dd6291-7fce-11e3-9d7d-82018f3b57b6",
           "application_id" : "fe02e19d-cd54-11e2-bf99-91e4d3e209c1",
           "batch_id" : null,
           "created_date" : "2014-01-17T23:23:45",
           "created_epoch" : 1390001025,
           "from" : "18586637982",
           "message" : "This is message 1",
           "status" : "sent",
           "to" : "13106681014",
           "type" : "incoming"
        },
        {
           "resource_id" : "0ffa6efc-797c-11e3-921c-e72f97aa6fc7",
           "application_id" : "fe02e19d-cd54-11e2-bf99-91e4d3e209c1",
           "batch_id" : null,
           "created_date" : "2014-01-09T22:19:10",
           "created_epoch" : 1389305950,
           "from" : "18586637982",
           "message" : "This is message 2",
           "status" : "sent",
           "to" : "13106681014",
           "type" : "incoming"
        },
        {
           "resource_id" : "754cd4c5-797b-11e3-9ee3-f553329d1061",
           "application_id" : "fe02e19d-cd54-11e2-bf99-91e4d3e209c1",
           "batch_id" : null,
           "created_date" : "2014-01-09T22:14:50",
           "created_epoch" : 1389305690,
           "from" : "13106681014",
           "message" : "This is message 3",
           "status" : "new",
           "to" : "18586637982",
           "type" : "outgoing"
        },
        {
           "resource_id" : "17df0c95-6c1c-11e3-816a-e7ef76005d7a",
           "application_id" : "fe02e19d-cd54-11e2-bf99-91e4d3e209c1",
           "batch_id" : null,
           "created_date" : "2013-12-23T21:49:26",
           "created_epoch" : 1387835366,
           "from" : "13106681014",
           "message" : "This is message 4",
           "status" : "new",
           "to" : "18586637982",
           "type" : "outgoing"
        },
        {
           "resource_id" : "1105bbb7-6c1c-11e3-9160-fd5c122c5a75",
           "application_id" : "fe02e19d-cd54-11e2-bf99-91e4d3e209c1",
           "batch_id" : null,
           "created_date" : "2013-12-23T21:49:15",
           "created_epoch" : 1387835355,
           "from" : "13106681014",
           "message" : "This is message 5",
           "status" : "new",
           "to" : "12012246523",
           "type" : "outgoing"
        }
     ],
     "links" : [
        {
           "next" : "https://v1.api.phone.com/sms?limit=5&offset=5"
        }
     ]
  }
}

Error Response

HTTP Code: 404 Not Found (Dependent resource not found)

Sample GET /sms Request (PHP)

Note that using GET /sms will retrieve a list of existing SMS messages in your account—either incoming (routed to your application) or outgoing.


<?php
$url = "https://v1.api.phone.com/sms/?limit=5&offset=0";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
// authentication
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");

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);
curl_close($ch);

if($info['http_code'] == 200) {
  echo $result;
} else {
  $error = array('http_code' => $info['http_code'], 'response' => $result);
  echo json_encode($error);
}
?>

Back to Methods Available for /sms.


DELETE /sms

Use DELETE /sms to remove all SMS messages that you have scheduled to send in the future (using the schedule_start and schedule_expire request body parameters). You must include delete_all to prevent you from deleting all of your scheduled sms objects by accident. Also, SMS objects being used by another object cannot be deleted.

Example

DELETE https://v1.api.phone.com/sms?delete_all=1

Authentication

This method requires authentication.

Parameters

Parameter Type Description
delete_all Boolean Set to 1 to complete the operation

Success Response

HTTP Code: 200 OK


{
 "response" : {
     "data" : "1"
   }
}

Error Response

  • HTTP Code: 400 Invalid Request
  • HTTP Code: 404 Not Found (Dependent resource not found)
  • HTTP Code: 409 Conflict (Name in Use)

Example for: HTTP Code 400


{
  "response" : {
     "error" : {
        "code" : 30605,
        "info" : "Error while processing request.",
        "url" : "https://docs.phone.com/refguides/errorref/generalerrors.html#error-code-30605"
     }
  }
}

Sample DELETE /sms Request (PHP)

Note that you must supply the delete_all argument to prevent you from deleting all your scheduled SMS objects by accident. Also, SMS objects being used by another object cannot be deleted.


<?php
$url = "https://v1.api.phone.com/sms?delete_all=1";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
// authentication
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

$info = curl_getinfo($ch);
curl_close($ch);

if($info['http_code'] == 200) {
  echo $result;
} else {
  $error = array('http_code' => $info['http_code'], 'response' => $result);
  echo json_encode($error);
}
?>

Back to Methods Available for /sms.


GET /sms/UUID

Use GET /sms/UUID to retrieve a specific SMS object.

Example

GET https://v1.api.phone.com/sms/UUID

Authentication

This method requires authentication.

Success Response

HTTP Code: 200 OK

Response Body Fields and Example

Field Type Values Description
status String   Indicates the state of your SMS objects
message String   Body of the SMS message text
to String   Configures which number will receive the SMS message
from String   Configures which number is displayed as the caller id
resource_id UUID   Resource_id of a valid SMS object
voip_id Integer   Your Phone.com API Developer account number
type String   Indicates whether the SMS object is inbound or outbound
application_id String   Your Phone.com API application key. This is the hexadecimal key that is automatically generated when you configure your application in your account.
batch_id UUID   Resource ID of the batch to which the SMS object belongs. When no batch is present, the value is null.
created_date String   Date string representing the UTC time that the object was created in the Phone.com API system. (ISO 8601 format)
created_epoch Integer   Unix time stamp representing the UTC time that the object was created in the Phone.com API system. (Unix time format)

Response Body Format Example

Example for: https://v1.api.phone.com/sms/e1186304-a5ec-11e2-8507-e90d08636c59


{
   "response" : {
      "data" : {
         "created_date" : "2014-01-17T23:23:45",
         "to" : "+15555551235",
         "resource_id" : "d8a35248-c488-11e2-9045-c4c757efeb33",
         "status" : "new",
         "from" : "+15555551234",
         "application_id" : "<application ID>",
         "message" : "Welcome to the Phone.com API"
      }
   }
}
            

Error Response

HTTP Code: 404 Not Found (Dependent resource not found)

Sample GET /sms/UUID Request (PHP)


<?php
$url = "https://v1.api.phone.com/GET/sms/89fa9c15-ced1-11e2-8d4d-e9333b439310";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
// authentication
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");

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);
curl_close($ch);

if($info['http_code'] == 200) {
  echo $result;
} else {
  $error = array('http_code' => $info['http_code'], 'response' => $result);
  echo json_encode($error);
}
?>

Back to Methods Available for /sms.


PUT /sms/UUID

Use PUT /sms/UUID to update a specific SMS object with new data. Note that you can only use PUT on an SMS object scheduled for a future date and time.

Important:

Also note that a PUT is not a PATCH. You need to send the complete object in the HTTP request body in order to update it.

Example

PUT https://v1.api.phone.com/sms/UUID

Authentication

This method requires authentication.

Request Body Fields and Example

Field Type Values Description
from E.164 Valid E.164 Caller ID to display on the outgoing SMS message. It must be a phone number associated with your account.
to E.164 Valid E.164 Phone number to which you are sending the outgoing SMS message.
message String Alphanumeric, underscore, and common punctuation Text body of the outgoing SMS message. Max. 160 characters per message. Longer messages are split into a maximum of three 160-character messages on your behalf.
schedule_start Integer/String Epoch seconds or `ISO 8601_ Start time for scheduled SMS event
schedule_expire Integer/String Epoch seconds or ISO 8601 Expire time for scheduled SMS event

Request Body Format Example


 {
   "from": "+15555551234",
   "to": "+15555551235",
   "message": "Welcome to the Phone.com API",
   "schedule_start": 1369346400,
   "schedule_expire": 1369348200
 }

Success Response

HTTP Code: 200 OK


{
  "response" : {
     "results" : "8621fd1d-ac35-11e2-8b76-9c78350b5f56"
  }
}

Error Response

  • HTTP Code: 404 Not Found (Dependent resource not found)
  • HTTP Code: 409 Conflict (Name in Use)
  • HTTP Code: 500 Internal Server Error

Example for: HTTP Code 404



{
   "error" : {
      "error_url" : "https://docs.phone.com/refguides/errorref/serviceerrors.html#error-code-30000",
      "error_code" : 30000,
      "error_info" : "The system could not locate the resource you requested."
   }
}

Sample PUT /sms/UUID Request (PHP)

The example below shows you how to use PUT /sms/UUID to update an SMS message scheduled to be delivered in the future.


<?php
$url = "https://v1.api.phone.com/v2/sms/c21a7a5c-ac39-11e2-8b76-a02ad1a2253c";

$put_body = <<<SMSDATA
{
  "from": "+15555551234",
  "to": "+15555551235",
  "message": "Welcome to the Phone.com API",
  "schedule_start": 1369346400,
  "schedule_expire": 1369348200
}
SMSDATA;

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
// authentication
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $put_body);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER,
           array('Content-Type: application/json',
                 'Content-Length: ' . strlen($put_body))
           );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

$info = curl_getinfo($ch);
curl_close($ch);

if($info['http_code'] == 200 || $info['http_code'] == 201) {
  echo $result;
} else {
  $error = array('http_code' => $info['http_code'], 'response' => $result);
  echo json_encode($error);
}

?>

Back to Methods Available for /sms.


DELETE /sms/UUID

Use DELETE /sms/UUID to delete a specific SMS object, scheduled for a future date and time. Note that you cannot delete an SMS object that is in use by another service.

Example

DELETE https://v1.api.phone.com/sms/UUID

Authentication

This method requires authentication.

Success Response

HTTP Code: 200 OK


{
  "response" : {
     "data" : "1"
  }
}

Error Response

  • HTTP Code: 400 Invalid Request
  • HTTP Code: 404 Not Found (Dependent Resource Not Found)
  • HTTP Code: 409 Conflict (Name in Use)

Example for: HTTP Code 409


{
  "response" : {
     "error" : {
        "code" : 30600,
        "info" : "The system could not locate the SMS you requested.",
        "url" : "https://docs.phone.com/refguides/errorref/serviceerrors.html#error-code-30600"
     }
  }
}

Sample DELETE /sms/UUID Request (PHP)


<?php
$url = "https://v1.api.phone.com/sms/80417048-ac3b-11e2-8b76-eea2f9d0a5a3";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
// authentication
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

$info = curl_getinfo($ch);
curl_close($ch);

if($info['http_code'] == 200) {
  echo $result;
} else {
  $error = array('http_code' => $info['http_code'], 'response' => $result);
  echo json_encode($error);
}
?>

Back to Methods Available for /sms.


Learn More: