SMS API
- NEW! - Interactive API docs, now live!
Visit api-docs.plumvoice.com to read Plum API documentation, build and test requests in our interactive API sandbox, review the responses, and share it all with your team.
Overview
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
<sample>
<status>success</status>
<error/>
<result>
<!-- SAMPLE RESULT DATA -->
</result>
</sample>
Special Notifications
Blocked numbers & landlines
Messages to unsubscribed numbers or landlines will fail, returning the message delivery status undelivered
. This also triggers an immediate notification describing why the messages failed.
The notification is for user information and will not appear as part of the response.
Examples:
Message sent to a phone number that previously sent a STOP request (i.e., unsubscribed):
{"status":"failure","error":""Attempt to send to unsubscribed recipient""}
Message sent to landline:
{"status":"failure","error":""To number: +1xxxxxxxxx, is not a mobile number""}
Sending SMS
Queue SMS
POST
https://hosting.plumvoice.com/ws/sms/{resource_type}
Queues an SMS message to be sent
Path Parameters
resource_type
string
queue.xml
or queue.json
Headers
Content-type
string
application/x-www-form-urlencoded
Accept
string
application/xml, application/json
Request Body
to
string
10-digit phone number that will receive the SMS message.
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.
Your SMS-enabled number must be non-PCI. SMS is unencrypted, which makes SMS messaging incompatible with PCI numbers and infrastructure.
body
string
SMS message to be sent Note: messages larger than 160 characters will be split into multiple messages.
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.
{
"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"
}
]
}
}
Sample Code
<?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);
?>
Receiving SMS
SMS Status
GET
https://hosting.plumvoice.com/ws/sms/{resource_type}/{sms_message_id}
Returns the status of an SMS message
Path Parameters
resource_type
string
status.xml
or status.json
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
Headers
content-type
string
application/x-www-form-urlencoded
accept
string
application/json, application/xml
{
"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"
}
}
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.
Failure: 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
<?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);
?>
Special Notifications
Blocked numbers & landlines
Messages to unsubscribed numbers or landlines will fail, returning the message delivery status undelivered
. This also triggers an immediate notification describing why the messages failed.
The notification is for user information and will not appear as part of the response.
Examples:
Message sent to a phone number that previously sent a STOP request (i.e., unsubscribed):
{"status":"failure","error":""Attempt to send to unsubscribed recipient""}
Message sent to landline:
{"status":"failure","error":""To number: +1xxxxxxxxx, is not a mobile number""}
SMS Messages
GET
https://hosting.plumvoice.com/ws/sms/{resource_type}
Lists SMS messages that have been sent and/or received.
Path Parameters
resource_type
string
messages.xml
or messages.json
Query Parameters
offset
integer
Number of SMS messages to skip before returning results
limit
integer
Maximum number of SMS messages to return. Note: minimum limit is 50, maximum limit is 1000.
order
string
Sort the SMS messages in ascending or descending order by date.
Accepted values are asc
, desc
, or blank
start_timestamp
integer
Start timestamp to begin searching for SMS messages.
end_timestamp
integer
End timestamp to stop searching for SMS messages.
msg_type
string
Type of messages to be returned.
Note: Accepted values are 'inbound', 'outbound', 'all' (for both inbound and outbound), or blank
.
phone_number
integer
The phone number to filter results on.
number_type
string
Available and required only when message type is inbound or outbound AND a phone number is provided. Note: accepted values are 'account' (your SMS phone number) and 'customer' (your end user's SMS phone number)
{
"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"
}
]
}
}
Sample Code
<?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);
?>
SMS Conversation
GET
https://hosting.plumvoice.com/ws/sms/{resource_type}
Lists messages between two phone numbers
Path Parameters
resource_type
string
conversation.xml
or conversation.json
Query Parameters
offset
integer
Number of SMS messages to skip before returning results.
limit
integer
Maximum number of SMS messages to return. Note: minimum limit is 50, maximum limit is 1000.
order
string
Sort the SMS messages in ascending or descending order by date.
Accepted values are asc
, desc
, or blank
start_timestamp
integer
Start timestamp to begin searching for SMS messages.
end_timestamp
integer
End timestamp to stop searching for SMS messages.
phone_number1
integer
First phone number to filter on for the returned conversation.
phone_number2
integer
Second phone number to filter on for the returned conversation.
{
"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"
}
]
}
}
Sample Code
<?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);
?>
Last updated