Plum offers four services for its SMS REST API:
Method | Service | Description |
POST | ||
GET | ||
GET | ||
GET | 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><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",}
queue.xml
or 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"}]}}
<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>
Sample Code
<?phpheader("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 optionscurl_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
status.xml
or 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","delivery_status":"delivered"}}
<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><delivery_status>delivered</delivery_status></result></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
.
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.
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.
Please be advised! The delivery status will only be available up to 7 days after the SMS message was sent.
Sample Code
<?phpheader("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 optionscurl_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
messages.xml
or messages.json
blank
.{"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"}]}}
<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>
Sample Code
<?phpheader("Content-type: text/xml");// initialize curl$ch = curl_init();// set necessary curl optionscurl_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"
conversation.xml
or conversation.json
{"status":"success","error":"","result":{"offset":"0","limit":"50","total":"4","sms_messages":[{"sms_message_id":"b84b2dbfadcc49e1a697aabfdb1f2730","to":"19998881234","from":"2435678910","body":"GREAT","request_timestamp":"1594662275","response_timestamp":"1594662276","result_url":"","type":"inbound","status":"received"},{"sms_message_id":"4beb4b8ace954ff694bdadb8cca99ac9","to":"2435678910","from":"19998881234","body":"Thanks for visiting us today! Tell us how we did. Reply back with \"OK\", \"GOOD\", \"GREAT\" or \"EXCELLENT\".","request_timestamp":"1594662276","response_timestamp":"1594662279","result_url":"","type":"outbound","status":"sent"},{"sms_message_id":"dd2ee079413f48b49e45879241af09d4","to":"19998881234","from":"2435678910","body":"CONFIRM","request_timestamp":"1594662276","response_timestamp":"1594662276","result_url":"","type":"inbound","status":"received"},{"sms_message_id":"6b8e2bd2e9e5485d9123ec929f462efd","to":"2435678910","from":"19998881234","body":"This is a notification of your appointment tomorrow. Please reply with \"CONFIRM\", to confirm your appointment.","request_timestamp":"1594662313","response_timestamp":"1594662314","result_url":"","type":"outbound","status":"sent"}]}}
<conversation><status>success</status><error></error><result><offset>0</offset><limit>50</limit><total>4</total><sms_messages><sms_message><sms_message_id>b84b2dbfadcc49e1a697aabfdb1f2730</sms_message_id><to>19998881234</to><from>2435678910</from><body>GREAT</body><request_timestamp>1594662275</request_timestamp><response_timestamp>1594662276</response_timestamp><result_url></result_url><type>inbound</type><status>received</status></sms_message><sms_message><sms_message_id>4beb4b8ace954ff694bdadb8cca99ac9</sms_message_id><to>2435678910</to><from>19998881234</from><body>Thanks for visiting us today! Tell us how we did. Reply back with "OK", "GOOD", "GREAT" or "EXCELLENT".</body><request_timestamp>1594662276</request_timestamp><response_timestamp>1594662279</response_timestamp><result_url></result_url><type>outbound</type><status>sent</status></sms_message><sms_message><sms_message_id>dd2ee079413f48b49e45879241af09d4</sms_message_id><to>19998881234</to><from>2435678910</from><body>CONFIRM</body><request_timestamp>1594662276</request_timestamp><response_timestamp>1594662276</response_timestamp><result_url></result_url><type>inbound</type><status>received</status></sms_message><sms_message><sms_message_id>6b8e2bd2e9e5485d9123ec929f462efd</sms_message_id><to>2435678910</to><from>19998881234</from><body>This is a notification of your appointment tomorrow. Please reply with "CONFIRM", to confirm your appointment.</body><request_timestamp>1594662313</request_timestamp><response_timestamp>1594662314</response_timestamp><result_url></result_url><type>outbound</type><status>sent</status></sms_message></sms_messages></result></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
<?phpheader("Content-type: text/xml");// initialize curl$ch = curl_init();// set necessary curl optionscurl_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"