Plum DEV Documentation
plumdevguide:smsoutbound

Outbound SMS Guide


Outbound SMS API Description

Plum offers three services for its SMS REST API:

Method Service Description
POST sms/queue Queues an SMS message and returns an SMS message resource
GET sms/status Returns a single SMS message resource
GET sms/messages Returns a filtered list of SMS message resources

Please note that each of these SMS REST APIs use HTTP AUTH for authentication. The username/password to be used for authentication are the same as your standard Plum DEV login credentials.

All of the SMS REST APIs have the same return format that includes a status (success or failure), error message and the result data.

Example Responses:

XML (success):

<sample>
  <status>success</status>
  <error/>
  <result>
    <!-- SAMPLE RESULT DATA -->
  </result>
</sample>

JSON (success):

{
  "status":"success",
  "error":"",
  "result": {
    // SAMPLE RESULT DATA
  }
}

XML (failure):

<sample>
  <status>failure</status>
  <error>Unauthorized access to sample service</error>
</sample>

JSON (failure):

{
  "status":"failure",
  "error":"Unauthorized access to sample service",
}


Queue SMS REST API (POST sms/queue)

Queues an SMS message to be sent.

Content-Type: application/x-www-form-urlencoded

Response Formats: JSON, XML

Requires HTTP Basic Authentication? Yes

Resource URL for XML-formatted Response: https://hosting.plumvoice.com/ws/sms/queue.xml

Resource URL for JSON-formatted Response: https://hosting.plumvoice.com/ws/sms/queue.json

Required POST Parameters:

Parameter Type Description
to string Phone number that the SMS message will be sent to
Note: you must include a '1' before the 10 digit phone number.
from string Phone number that the SMS will appear from
Note: this phone number must appear as an “SMS Number” on the “Account Configuration” page in your Plum DEV account. Any attempt to send an SMS using a number not listed as an “SMS Number” in your account will fail.
body string SMS message to be sent
Note: messages larger than 160 characters will be split into multiple messages.

Optional Parameters:

Parameter Type Description
result_url string URL for tracking the SMS result status
Note: after the SMS is sent this URL will receive a POST with the following variables: 'sms_message_id' and 'status'. This should be used to get the status of an SMS message rather than polling the status REST service.

Example Responses:

XML:

<queue>
  <status>success</status>
  <error/>
  <result>
    <sms_messages>
      <sms_message>
        <sms_message_id>e7f41fdc813d481081ec2840d68838b5</sms_message_id>
        <to>19998881234</to>
        <from>2435678910</from>
        <body>This is a notification</body>
        <request_timestamp>1330464356</request_timestamp>
        <result_url>http://myserver.com/storesmsresults.php<result_url>
        <status>queued</status>
      </sms_message>
    </sms_messages>
  </result>
</queue>

JSON:

{
  "status":"success",
  "error":"",
  "result": {
    "sms_messages": [
      {
        "sms_message_id":"e7f41fdc813d481081ec2840d68838b5",
        "to":"19998881234",
        "from":"2435678910",
        "body":"This is a notification",
        "request_timestamp":1330464356,
        "result_url":"http://myserver.com/storesmsresults.php",
        "status":"queued"
      }
    ]
  }
}

Try it out:

parameters
result format
to
from * appears in your Plum DEV account as an SMS Number
body
result url

PHP Code Example:

queuesms.php

<?php
header("Content-type: text/xml");

$params['to'] = "19998881234";
$params['from'] = "2435678910";
$params['body'] = "This is a notification.";
$params['result_url'] = "http://myserver.com/storesmsresults.php";

// initialize curl
$ch = curl_init();

// set necessary curl options
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_URL, "https://hosting.plumvoice.com/ws/sms/queue.xml");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");

echo(curl_exec($ch));

curl_close($ch);
?>

storesmsresults.php:

<?php
// make sure the log file has read/write permissions from the web server
$logfile = "logs/smsresults.log"
if (!is_readable($logfile) || !is_writable($logfile)) {
  die("Unable to write to log file.");
}

if (isset($_POST['sms_message_id'], $_POST['status'])) {
  if ($fp = fopen($logfile, 'a+')) {
    $date = date("r");
    $message_id = $_POST['sms_message_id'];
    $status = $_POST['status'];
    fwrite($fp, "$date $message_id $status\n");
    fclose($fp);
  }
}
?>

CURL Example from the Command Line:

curl -u username:password -d to=19998881234 -d from=2435678910 -d body='This is a notification' https://hosting.plumvoice.com/ws/sms/queue.xml


Status SMS REST API (GET sms/status)

Returns the status of an SMS message.

Content-Type: application/x-www-form-urlencoded

Response Formats: JSON, XML

Requires HTTP Basic Authentication? Yes

Resource URL for XML-formatted Response: https://hosting.plumvoice.com/ws/sms/status.xml/{sms_message_id}

Resource URL for JSON-formatted Response: https://hosting.plumvoice.com/ws/sms/status.json/{sms_message_id}

Required Resource Parameters:

Parameter Type Description
sms_message_id string Unique 128-bit hexidecimal identifier for this SMS message
Note: this value is provided in the result of a queued SMS message

Example Responses:

XML:

<status>
  <status>success</status>
  <error/>
  <result>
    <sms_message_id>e7f41fdc813d481081ec2840d68838b5</sms_message_id>
    <to>19998881234</to>
    <from>2435678910</from>
    <body>This is a notification</body>
    <request_timestamp>1330464356</request_timestamp>
    <response_timestamp>1330464357</response_timestamp>
    <status>sent</status>
  </result>
</status>

JSON:

{
  "status":"success",
  "error":"",
  "result": {
    "sms_message_id":"e7f41fdc813d481081ec2840d68838b5",
    "to":"19998881234",
    "from":"2435678910",
    "body":"This is a notification",
    "request_timestamp":"1330464356",
    "response_timestamp":"1330464357",
    "status":"sent"
  }
}

PHP Code Example:

checkstatus.php

<?php
header("Content-type: text/xml");

// for this example, our sms_message_id is e7f41fdc813d481081ec2840d68838b5
$sms_message_id = 'e7f41fdc813d481081ec2840d68838b5';

// initialize curl
$ch = curl_init();

// set necessary curl options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
curl_setopt($ch, CURLOPT_URL, "https://hosting.plumvoice.com/ws/sms/status.xml/".$sms_message_id);

echo(curl_exec($ch));

curl_close($ch);
?>

CURL Example from the Command Line:

curl -u username:password https://hosting.plumvoice.com/ws/sms/status.json/e7f41fdc813d481081ec2840d68838b5


Listing SMS Messages (GET sms/messages)

Lists SMS messages that have been sent or received.

Content-Type: application/x-www-form-urlencoded

Response Formats: JSON, XML

Requires HTTP Basic Authentication? Yes

Resource URL for XML-formatted Response: https://hosting.plumvoice.com/ws/sms/messages.xml

Resource URL for JSON-formatted Response: https://hosting.plumvoice.com/ws/sms/messages.json

Optional GET Parameters:

Parameters Type Description
offset int Number of SMS messages to skip before returning results
limit int Maximum number of SMS message to return
Note: minimum limit is 50, maximum limit is 1000
start_timestamp int Start timestamp to begin searching for SMS messages
end_timestamp int End timestamp to stop searching for SMS messages

Example Responses:

XML:

<messages>
  <status>success</status>
  <error/>
  <result>
    <offset>0</offset>
    <limit>50</limit>
    <total>2</total>
    <sms_messages>
      <sms_message>
        <sms_message_id>e7f41fdc813d481081ec2840d68838b5</sms_message_id>
        <to>19998881234</to>
        <from>2435678910</from>
        <body>This is a notification</body>
        <request_timestamp>1330464356</request_timestamp>
        <response_timestamp>1330464357</response_timestamp>
        <result_url/>
        <status>sent</status>
      </sms_message>
      <sms_message>
        <sms_message_id>bf811cfb5e864a2793d9b6b81ec2185f</sms_message_id>
        <to>19998881234</to>
        <from>2435678910</from>
        <body>Resending notification</body>
        <request_timestamp>1330464386</request_timestamp>
        <response_timestamp>1330464387</response_timestamp>
        <result_url/>
        <status>sent</status>
      </sms_message>
    </sms_messages>
  </result>
</messages>

JSON:

{
  "status":"success",
  "error":"",
  "result": {
    "offset":0,
    "limit":50,
    "total":"2",
    "sms_messages": [
      {
        "sms_message_id":"e7f41fdc813d481081ec2840d68838b5",
        "to":"19998881234",
        "from":"2435678910",
        "body":"This is a notification",
        "request_timestamp":"1330464356",
        "response_timestamp":"1330464357",
        "result_url":"",
        "status":"sent"
      },
      {
        "sms_message_id":"bf811cfb5e864a2793d9b6b81ec2185f",
        "to":"19998881234",
        "from":"2435678910",
        "body":"Resending notification",
        "request_timestamp":"1330464386",
        "response_timestamp":"1330464387",
        "result_url":"",
        "status":"sent"
      }
    ]
  }
}

PHP Code Example:

checkmessages.php

<?php
header("Content-type: text/xml");

// initialize curl
$ch = curl_init();

// set necessary curl options
curl_setopt($ch, CURLOPT_URL, "https://hosting.plumvoice.com/ws/sms/messages.xml?offset=0&limit=50&start_timestamp=0&end_timestamp=0");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");

echo(curl_exec($ch));

curl_close($ch);
?>

CURL Example from the Command Line:

curl -u username:password "https://hosting.plumvoice.com/ws/sms/messages.json/?offset=0&limit=50&start_timestamp=0&end_timestamp=0"