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)
1
<sample>
2
  <status>success</status>
3
  <error/>
4
  <result>
5
    <!-- SAMPLE RESULT DATA -->
6
  </result>
7
</sample>
Copied!
1
<sample>
2
  <status>failure</status>
3
  <error>Unauthorized access to sample service</error>
4
</sample>
Copied!
1
{
2
  "status":"success",
3
  "error":"",
4
  "result": {
5
    // SAMPLE RESULT DATA
6
  }
7
}
Copied!
1
{
2
  "status":"failure",
3
  "error":"Unauthorized access to sample service",
4
}
Copied!
1
{
2
  "status":"failure",
3
  "error":"Invalid 'to' phone number",
4
}
Copied!
Sending SMS
post
https://hosting.plumvoice.com
/ws/sms/{resource_type}
Queue SMS
Sample Code
queuesms.php
storesmsresults.php
CURL (command line)
1
<?php
2
header("Content-type: text/xml");
3
​
4
$params['to'] = "19998881234";
5
$params['from'] = "2435678910";
6
$params['body'] = "This is a notification.";
7
$params['result_url'] = "http://myserver.com/storesmsresults.php";
8
​
9
// initialize curl
10
$ch = curl_init();
11
​
12
// set necessary curl options
13
curl_setopt($ch, CURLOPT_POST, 1);
14
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
15
curl_setopt($ch, CURLOPT_URL, "https://hosting.plumvoice.com/ws/sms/queue.xml");
16
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
17
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
18
​
19
echo(curl_exec($ch));
20
​
21
curl_close($ch);
22
?>
Copied!
1
<?php
2
// make sure the log file has read/write permissions from the web server
3
$logfile = "logs/smsresults.log"
4
if (!is_readable($logfile) || !is_writable($logfile)) {
5
  die("Unable to write to log file.");
6
}
7
​
8
if (isset($_POST['sms_message_id'], $_POST['status'])) {
9
  if ($fp = fopen($logfile, 'a+')) {
10
    $date = date("r");
11
    $message_id = $_POST['sms_message_id'];
12
    $status = $_POST['status'];
13
    fwrite($fp, "$date $message_id $status\n");
14
    fclose($fp);
15
  }
16
}
17
?>
Copied!
1
curl -u username:password -d to=19998881234 -d from=2435678910 -d body='This is a notification' https://hosting.plumvoice.com/ws/sms/queue.xml
Copied!
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)
1
<?php
2
header("Content-type: text/xml");
3
​
4
// for this example, our sms_message_id is e7f41fdc813d481081ec2840d68838b5
5
$sms_message_id = 'e7f41fdc813d481081ec2840d68838b5';
6
​
7
// initialize curl
8
$ch = curl_init();
9
​
10
// set necessary curl options
11
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
12
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
13
curl_setopt($ch, CURLOPT_URL, "https://hosting.plumvoice.com/ws/sms/status.xml/".$sms_message_id);
14
​
15
echo(curl_exec($ch));
16
​
17
curl_close($ch);
18
?>
Copied!
1
curl -u username:password https://hosting.plumvoice.com/ws/sms/status.json/e7f41fdc813d481081ec2840d68838b5
Copied!
get
https://hosting.plumvoice.com
/ws/sms/{resource_type}
SMS Messages
Sample Code
getmessages.php
CURL (command line)
1
<?php
2
header("Content-type: text/xml");
3
​
4
// initialize curl
5
$ch = curl_init();
6
​
7
// set necessary curl options
8
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");
9
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
10
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
11
​
12
echo(curl_exec($ch));
13
​
14
curl_close($ch);
15
?>
Copied!
1
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"
Copied!
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)
1
<?php
2
header("Content-type: text/xml");
3
​
4
// initialize curl
5
$ch = curl_init();
6
​
7
// set necessary curl options
8
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");
9
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
10
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
11
​
12
echo(curl_exec($ch));
13
​
14
curl_close($ch);
15
?>
Copied!
1
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"
Copied!
Legacy and Miscellaneous Notes
Next - Plum DEV APIs
Call Logs API
Last modified 3mo ago
Copy link
Contents