Search…
SMS API

SMS API Descriptions

Plum offers four services for its SMS REST API:
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!
Last modified 3mo ago