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>

<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",
}

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

Name

Type

Description

Headers

Name

Type

Description

Request Body

Name

Type

Description

{
  "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

<?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

SMS Status

GET https://hosting.plumvoice.com/ws/sms/{resource_type}/{sms_message_id}

Returns the status of an SMS message

Path Parameters

Name

Type

Description

Headers

Name

Type

Description

{
  "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.

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);
?>

curl -u username:password https://hosting.plumvoice.com/ws/sms/status.json/e7f41fdc813d481081ec2840d68838b5

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

Name

Type

Description

Query Parameters

Name

Type

Description

{
  "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

<?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"

SMS Conversation

GET https://hosting.plumvoice.com/ws/sms/{resource_type}

Lists messages between two phone numbers

Path Parameters

Name

Type

Description

Query Parameters

Name

Type

Description

{
  "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

<?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"

PreviousLegacy and Miscellaneous Notes NextCall Logs API

Last updated 1 year ago