SMS API

Search…
SMS API
SMS API Descriptions
Plum offers four 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​
​GET​
​sms/conversation​
​Returns SMS messages exchanged between two defined phone numbers​
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.
Sample Responses
XML (success)
XML (failure)
JSON (success)
 JSON (failure)
JSON (invalid phone number)
<sample>
  <status>success</status>
  <error/>
  <result>
    <!-- SAMPLE RESULT DATA -->
  </result>
</sample>
<sample>
  <status>failure</status>
  <error>Unauthorized access to sample service</error>
</sample>
{
  "status":"success",
  "error":"",
  "result": {
    // SAMPLE RESULT DATA
  }
}
{
  "status":"failure",
  "error":"Unauthorized access to sample service",
}
{
  "status":"failure",
  "error":"Invalid 'to' phone number",
}
Sending SMS
post
https://hosting.plumvoice.com
/ws/sms/{resource_type}
Queue SMS
Sample Code
queuesms.php
storesmsresults.php
CURL (command line)
<?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);
?>
<?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 -u username:password -d to=19998881234 -d from=2435678910 -d body='This is a notification' https://hosting.plumvoice.com/ws/sms/queue.xml
Receiving SMS
get
https://hosting.plumvoice.com
/ws/sms/{resource_type}/{sms_message_id}
SMS Status
This method with return result status as queued, sent, received, or failed. When the value of status is sent, then the method will also return a result delivery_status as delivered or undelivered.
Statuses Explained
Message Status Types:
Queued: your message has been added to the queue to be sent.
Sent: your message has been sent.
Received: you have received an incoming message.
Failed: your message could not be sent. Failed messages can happen for a variety of reasons including queue overflows, account suspensions, etc.
Delivery Status Types:
Delivered: your message has been successfully delivered to your recipient.
Undelivered: your message was not delivered. There are many reasons why this may occur including, destination number is not a mobile number, carrier content filtering, the availability of the destination number, etc.
Unconfirmed: There is no indication whether or not your message reached your recipient.
Please be advised! The delivery status will only be available up to 7 days after the SMS message was sent.
Sample Code
checkstatus.php
CURL (command line)
<?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 -u username:password https://hosting.plumvoice.com/ws/sms/status.json/e7f41fdc813d481081ec2840d68838b5
get
https://hosting.plumvoice.com
/ws/sms/{resource_type}
SMS Messages
Sample Code
getmessages.php
CURL (command line)
<?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&msg_type=inbound&phone_number=xxxxxxxxxx&number_type=account");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
​
echo(curl_exec($ch));
​
curl_close($ch);
?>
curl -u username:password "https://hosting.plumvoice.com/ws/sms/messages.json/?offset=0&limit=50&start_timestamp=0&end_timestamp=0&msg_type=inbound&phone_number=xxxxxxxxxx&number_type=account"
get
https://hosting.plumvoice.com
/ws/sms/{resource_type}
SMS Conversation
Be sure to filter based on your Plum-provided SMS number and the end-user's phone number to yield the correct results. Use the phone_number1 or phone_number2 parameters with either filtered number.
Sample Code
getconversation.php
CURL (command line)
<?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/conversation.xml?offset=0&limit=50&start_timestamp=0&end_timestamp=0&phone_number1=xxxxxxxxxx&phone_number2=xxxxxxxxxx");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
​
echo(curl_exec($ch));
​
curl_close($ch);
?>
curl -u username:password "https://hosting.plumvoice.com/ws/sms/messages.json/?offset=0&limit=50&start_timestamp=0&end_timestamp=0&phone_number1=xxxxxxxxxxx&phone_number2=xxxxxxxxxx"
Legacy and Miscellaneous Notes
Next - Plum DEV APIs
Call Logs API
Last modified 4mo ago
Copy link
Outline