SMS Guide

Overview

Plum DEV allows customers to manage the sending and receiving of SMS messages. This guide covers four basic aspects of SMS messaging: sending, receiving, logs, and result URLs.

Current customers seeking to add SMS functionality to their account should contact Plum Voice Account Management for pricing.

The first step to building SMS functionality into voice applications is to procure an SMS-ready phone number. Current customers can do this by sending a request to Plum Provisioning.

IMPORTANT! Your SMS-enabled number must be non-PCI. SMS is unencrypted, which makes SMS messaging incompatible with PCI numbers and infrastructure.

The most efficient way to leverage SMS in Plum DEV is through the use of APIs.

Sending SMS Messages

Once Plum customers obtain an SMS-ready phone number, they are able to use the Queue SMS API to send SMS messages. No additional setup is necessary.

As outlined in the Queue SMS API, to send an API requires a destination phone number (to), an origination phone number (from), and the message (body).

More advanced use cases may choose to employ the result URL parameter.

Result URL

A given SMS can have a range of statuses, depending on where it is in the sending process, e.g., queued, sent, received, failed. Users may wish to know the status of an SMS message and the result URL parameter provides that information without having to utilize multiple Get Status requests.

With result URL, the Plum system sends the SMS message, it also sends the message ID and status to the user's result URL. Plum sends the most recent SMS status we receive to the user's result URL.

Users can set up notifications around these updates or use the data for any other purposes they see fit. This may include writing the data to a file, updating a database, pushing notifications to end users, etc

Users must host and provide the actual result URL, e.g., http://user.server.com/sms_status_catcher/.

An example of how to use the result_url parameter is in the queuesms.php code sample (line 7) under the Queue SMS method.

Receiving SMS Messages

Customers that want to receive SMS messages must have an SMS-ready phone number active in their Plum Voice account.

Furthermore, customers must configure and application URL for receiving SMS messages.

Configuring an Application URL

It is necessary to set an application URL in order to receive incoming messages on an SMS-enabled phone number. To configure an application URL, go to the SMS Applications section to display a list of the SMS-enabled numbers associated with your account. Click the “Edit” link for the desire number.

This opens an application configuration page. Enter the URL for the webserver that will handle your incoming SMS message in the Application URL textbox. Click the 'Save' button to apply the changes.

Once you save a new SMS application, it gets added to your SMS Application list:

Replying to SMS Messages

When an HTTP POST gets sent to your application URL, the expected response is a well-formed XML document that adheres to the Plum Voice SMS Reply Schema. The simplest valid response consists of an XML prologue and a <reply> tag.

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:element name="reply" type="reply"/>
  <xs:complexType name="reply">
    <xs:sequence>
      <xs:element name="sms_message" minOccurs="0" maxOccurs="unbounded">
        <xs:complexType>
          <xs:simpleContent>
            <xs:extension base="xs:string">
              <xs:attribute name="to" type="xs:string"/>
              <xs:attribute name="from" type="xs:string"/>
              <xs:attribute name="result_url" type="xs:anyURI"/>
            </xs:extension>
          </xs:simpleContent>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

The following example does nothing with the incoming SMS message.

<?xml version="1.0"?>
<reply/>

It is possible to use the response to the HTTP POST request to send one or more SMS messages in reply. The DEV platform validates and parses the response and sends one SMS message for each <sms_message> tag. To reply to the sender of the incoming SMS message, place the response message inside a single <sms_message> tag.

<?xml version="1.0"?>
<reply>
    <sms_message>thanks for the message!</sms_message>
</reply>

SMS Message Logs

IMPORTANT: Logging is not available on demo accounts.

Demo accounts provide only limited access to DEV's product features. You'll need a standard account for full access to logging and more.

Using a demo account? Contact us if interested in upgrading to a standard account.

The Plum platform creates a record for each SMS message sent or received through your account. Each record contains the following information:

To (recipient)
From (sender)
Timestamp
Status (received, queued, or sent)
Type (inbound, outbound, or reply)

Greater detail about an SMS message is available by clicking the 'View' link. The detailed view includes the data listed in the Message Log table, plus the body of the message and the result URL, if provided:

sms_message_id

Unique 128-bit hexidecimal identifier for this SMS message

Phone number that received the SMS message

from

Phone number that sent the SMS message

body

Contents of the SMS message