Plum DEV Documentation
plumdevguide:smsinbound

Inbound SMS Guide

Configuring an Application URL

The Plum Voice Inbound SMS platform allows you to specify an application URL that that can be used to receive incoming messages on your SMS phone numbers. To configure an application URL, first click on “Edit” for one of your SMS numbers.

From there, enter your URL within the Application URL textbox.

Receiving an SMS Message

Your application URL must accept incoming HTTP POST requests in order to process an SMS message. When an SMS message is received by Plum Voice the following POST variables will be sent to your application URL:

POST Variable Description
sms_message_id Unique 128-bit hexidecimal identifier for this SMS message
to Phone number that received the SMS message
from Phone number that sent the SMS message
body Contents of the SMS message

Replying to SMS Messages

The expected response when an HTTP POST is sent to your application URL 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. The example below does nothing with the incoming SMS message.

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

You can also use your response to the HTTP POST request to send one or more SMS messages in reply. The Plum Voice Inbound SMS platform will validate and parse your response and send one SMS message for each <sms_message> tag. To reply to the sender of the incoming SMS message you can place your message inside a single <sms_message> tag.

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

The <sms_message> Tag

The <sms_message> tag supports a number of optional parameters that can be used to build more advanced SMS applications. These attributes give you the ability to send SMS messages to multiple recipients from any of your SMS numbers as well as setting up callback URLs so that you can be notified when the messages have been sent. Here is the full list of supported attributes:

Attribute Description
to Phone number that the SMS message will be sent to
Note: You must include a '1' before the 10 digit phone number. If the 'to' attribute is not provided, the default is set to the originating phone number that sent the SMS message.
from 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 reply using an SMS using a number not listed as an “SMS Number” in your account will fail. If the 'from' attribute is not provided, the default is set to the SMS number that received the SMS message.
result_url 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. If the 'result_url' attribute is not provided, the default is set to no result URL being used.

Here is an example application that sends three SMS messages as a response to an incoming message:

<?xml version="1.0"?>
<reply>
    <sms_message to="12125550000" from="6177123000">Yeah, mom's awesome. We should call her!</sms_message>
    <sms_message to="12125550001" from="6177123000">There's always money in the banana stand!</sms_message>
    <sms_message to="12125550002" from="6177123000">Return from whence you came!</sms_message>
</reply>

Group Messaging Example

Here is an example application that could be used to perform group messaging using the Plum Voice Inbound SMS platform:

group_messaging.php

<?php
header('Content-type: text/xml');
echo("<?xml version=\"1.0\"?>\n");

// The list of people in this group
$group = array('12125550000'=>'Michael', '12125550001'=>'Buster', '12125550002'=>'Lindsay', '12125550003'=>'GOB');

// Make sure the sender is part of this group
if ( isset($_POST['from']) && isset($group[$_POST['from']]) ) {
  echo('<reply>');

  // Reply to everyone except the sender
  foreach ($group as $to=>$contact) {
    if ($to != $_POST['from']) {
      echo("<sms_message to=\"$to\">".htmlspecialchars($_POST['body']).'</sms_message>');
    }
  }
  echo('</reply>');
} 
else { echo('<reply/>'); }
?>

From this example, we've created a messaging group consisting of four people. The SMS request POSTs the “from” variable and we can set up our code to exclude the sender from our reply. We can also use the POST variable “body” to forward the message on to everyone else in the group.

The code allows for the following SMS exchange:

Michael: The banana stand is on fire!

(Buster, Lindsay and GOB receive SMS message)

Buster: Again?

(Michael, Lindsay and GOB receive SMS message)

Michael: One of you mailed in that insurance check, right?

(Buster, Lindsay and GOB receive SMS message)

GOB: Oh, I mailed your check, Michael.

(Michael, Buster and Lindsay receive SMS message)

Lindsay: No, he didn't.

(Michael, Buster and GOB receive SMS message)

SMS Message Logs

For each SMS message that was sent or received on your account, a record will be created. When an SMS message is sent to or from one of your SMS numbers, you'll see information for To, From, Timestamp, Status (received, queued or sent), and Type (inbound, outbound or reply).

If you were to click on “View” for one of your SMS logs, you would see the same information listed above along with the Body of the message and a Result URL, if one was provided:

Debugging

If you ever run into errors for your SMS application, the error logs can be used to help you debug those errors.

To look at the error logs, click on the “Error Logs” header under SMS Applications and click on “View” for one of your SMS Errors.

There, you'll be able to see the error that was generated, including the SMS request, the XML response, and highlighting the line of code that's causing the error (if applicable).