Categories

Popular Topics

Authoring Best Practices Browsers Content Adaptation Devices HTML5 Mobile Design Web Publishing Responsive Design User Experience WebPerf All Topics »

Receiving SMS Messages via Shortcodes & Keywords

, by mokil

Back around 1998, more and more billboards started to display some odd messages, along the lines of “Visit us on the web at www.companyname.com”. This was a major shift in advertising and gave marketers another avenue to explore. It was, of course, the beginning of the Internet’s move from academia to the mainstream, and the proliferation of Web sites seemed to happen almost overnight.

Here in 2010, we’re now back in 1998 territory. This time it’s the mobile Web that has everybody excited. The thought of potential customers being able to access services from anywhere – and not just in front of a PC – has marketers drooling. SMS plays an important role. On billboards ads, one is very likely to see something like “text companyname to 81707 for more information”. This is a shortcode/keyword combination. By texting the specified keyword (companyname in the example above) to the specified shortcode (81707 in the example), a mobile system can perform some type of action, defined by the company offering the keyword/shortcode. This may be as simple as sending a “Thanks for contacting us, we’ll be in touch” message back to the user, or beginning some kind of workflow process. Or, as in our example above, the user may receive a text message back containing a URL to a mobile Web site.

But just how do developers go about setting up keyword/shortcodes? And how do they process incoming messages to those keyword/shortcodes? Let’s take a look at how to do this. We’ll build upon the system we’ve built in previous articles that allows us to send SMS messages and to process delivery receipts. We’ll build on the basic message processing system we built in the delivery receipts article. Remember we’re using SQL Server and Visual Studio (C#) to build our system.

Obtaining a Keyword/Shortcode

In the Sending SMS Messages article, we talked about ways of sending SMS messages, and demonstrated how to do this using an aggregator called iTagg. We also need to use an aggregator to set up keyword/shortcodes. You have two options here:

  • Purchase a dedicated shortcode This is the expensive option. Expect to pay several thousand pounds for a dedicated shortcode. ITV, for example, has the dedicated shortcode 63330. This means ITV can set up any keyword they like on this shortcode; no other company has access to it. It is purely for ITV’s exclusive use.
  • Purchase a keyword on a shared shortcode This is what most companies use. An aggregator provides a shared shortcode (so called because several companies use keywords on the same shortcode), and the aggregator’s clients purchase keywords to use on it. iTagg own the shared shortcode 60300. So client 1 may purchase the keyword mobile. If client 2 comes along and also wants the keyword mobile, they cannot have it as it has already been assigned. Client 2 would have to select an alternative keyword.

The costs of purchasing a keyword/shortcode vary from aggregator to aggregator. You can expect to pay a monthly or annual fee for the use of the platform and a monthly rental fee for the keyword/shortcode. Some aggregators allow you to pay a fee and have a certain number of keywords – contact the aggregators to determine what price point works best for you.

One last important point – make sure you choose your aggregator carefully. Once you’ve chosen an aggregator any advertising of your keyword/shortcode will be showing the shared shortcode used by the aggregator – effectively locking you in. I strongly recommend you run some tests with the aggregators you’re interested in before making a final decision.

Configuring a Keyword/Shortcode

Once you have a keyword/shortcode, how do you set it up? It’s pretty easy. You give the aggregator a Web address, and the aggregator forwards any inbound messages they receive on your keyword/shortcode to the specified Web address. Depending upon the aggregator, there are two ways you can provide the Web address:

  • Provide the Web address to the aggregator’s support team, who will then configure it for you (this is the only method of configuration for certain aggregators)
  • Log on to the aggregator’s control panel and change the URL yourself

The second option is much preferred, as it gives you the ability to quickly change the URL yourself. The first option puts a reliance on the aggregator’s support team.

Here’s the iTagg control panel, listing available keywords:



Figure 1 iTagg Control Panel

Clicking on the keyword allows you to configure details for the keyword/shortcode. There are a number of options – you can choose to forward messages on to a URL, and/or to an e-mail address. Clicking on the E-mail/URL Forwarder option displays a screen allowing you to configure the relevant pieces of information:



Figure 2 Configuring Keyword URL

Once you’ve configured these pieces of information, you’re ready to receive inbound SMS messages – as long as you have a system present to process them, of course. Let’s build that system after we’ve looked at how iTagg send inbound messages to us.

iTagg Inbound Messages

iTagg send all inbound SMS message requests over HTTP POST. Here are the parameters iTagg send to our Web listener page:

  • Source This is the mobile number the message was sent from. So if you sent the message from your mobile number, the value for this field would be your mobile number
  • Dest The shortcode the message was delivered to, e.g. 60300
  • Dtime The delivery time of the message from the mobile network – in the format YYYYMMDDHHMM.
  • Message The message body received
  • Network The network the source mobile number uses. This is passed as a code:
    • 10 – O2
    • 15 – Vodafone
    • 20 – 3
    • 30 – T-Mobile/Virgin
    • 33 – Orange
    • 99 – Other

    Different aggregators use different codes

  • Message_id The unique identifier assigned to the message by the aggregator
  • Message_after_match Message_after_match contains the body of the message sent after the keyword has been matched
  • Matched_keyword This is the keyword that was matched. This can be used to quickly match up keywords in multi-keyword systems
  • Matched_subkeyword This is usually blank. iTagg allows keywords to be set up as sub-keywords (e.g. “example” could be extended with sub-keywords 1, 2 – so the user would send “example1” and “example2”

Note that these parameters are specific to iTagg – they will differ for each individual aggregator. For example, Tanla pass the following parameters:

  • ServiceID (Tanla service number)
  • MOID (aggregator ID)
  • Operator ID (denotes which network the sender uses)
  • Date (date/time the message was received)
  • From (the mobile number the message was sent from)
  • To (the shortcode the message was sent to)
  • Message (the message body)

It’s important to look at the API documents for the aggregator you’re planning to use (iTagg’s API documents can be found at their Web site). Using iTagg, let’s enhance our existing system to process inbound messages.

Building the Database

Here’s the SQL Server database script from the delivery receipts article, with one minor alteration:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
USE master
 
-- Delete the database if it already exists
IF EXISTS(SELECT [name] FROM sys.databases
    WHERE [name] = 'MobiforgeMessageDemo')
BEGIN
DROP DATABASE MobiforgeMessageDemo
END
GO
 
-- Create the database
CREATE DATABASE MobiforgeMessageDemo
 
GO
 
USE MobiforgeMessageDemo
 
-- Add the Messages table
CREATE TABLE [Messages]
(
AggregatorMessageID VARCHAR(40),
InboundMessage BIT,
Originator VARCHAR(12),
Recipient VARCHAR(12),
MessageDate DATETIME DEFAULT GETDATE(),
MessageBody VARCHAR(160),
MessageDelivered BIT DEFAULT 0
)
 
GO
 
-- Stored procedure to insert a message
-- Amended to accept an optional Message Date
CREATE PROCEDURE usp_InsertMessage
@AggregatorMessageID VARCHAR(40),
@InboundMessage BIT,
@Originator VARCHAR(12),
@Recipient VARCHAR(12),
@MessageBody VARCHAR(160),
@MessageDate DATETIME = NULL
AS
BEGIN
 
SET NOCOUNT ON
 
IF (@MessageDate IS NULL)
BEGIN
INSERT INTO [Messages]
(AggregatorMessageID, InboundMessage, Originator,
Recipient, MessageBody)
VALUES
(@AggregatorMessageID, @InboundMessage, @Originator,
@Recipient, @MessageBody)
END
ELSE
BEGIN
INSERT INTO [Messages]
(AggregatorMessageID, InboundMessage, Originator,
Recipient, MessageBody, MessageDate)
VALUES
(@AggregatorMessageID, @InboundMessage, @Originator,
@Recipient, @MessageBody, @MessageDate)
END
  
SET NOCOUNT OFF
 
END
 
GO
 
-- Stored procedure to update a message's delivery status
CREATE PROCEDURE usp_MarkMessageAsDelivered
@AggregatorMessageID VARCHAR(40)
AS
BEGIN
 
SET NOCOUNT ON
 
-- iTagg pass message IDs with a -3 when sending messages,
-- but do not pass the -3 in delivery receipts. So we check
-- if we can find the message first, and if we can't we append
-- a -3 to the end of the ID
IF NOT EXISTS (SELECT AggregatorMessageID
   FROM [Messages]
   WHERE AggregatorMessageID = @AggregatorMessageID)
BEGIN
 
SET @AggregatorMessageID += '-3'
 
END   
 
UPDATE [Messages]
SET MessageDelivered = 1
WHERE AggregatorMessageID = @AggregatorMessageID
 
END

We’ve made one change to this script – in the usp_InsertMessage stored procedure. We’ve added an optional @MessageDate parameter. If this is passed we insert the date into the table; otherwise we use the current date/time.

Amending the Listener Web Page

When we added the ability to process delivery receipts to our simple messaging system, we introduced a listener Web page. We configured this in the iTagg control panel. We’ll now amend the listener to detect whether a delivery receipt or inbound message has been received, and we’ll process it accordingly.

Here’s the original code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
protected void Page_Load(object sender, EventArgs e)
{
try
{
  // Check if some POST data was passed
  if (Request.InputStream != null)
  {
   StreamReader sr = new StreamReader(Request.InputStream);
 
   // Convert the POST stream to a string
   // We remove the xml= tag at the front, otherwise the XML will not parse
   string inputStream = sr.ReadToEnd().Replace("xml=", string.Empty);
                
   // Create a delivery receipt
   iTaggDeliveryRecipt dr = new iTaggDeliveryRecipt(inputStream);
 
   // Write out the delivery receipt details to the trace
   Trace.Write("iTagg DR data: " + inputStream);
 
   Trace.Write("DR submission ref: " + dr.SubmissionRef);
   Trace.Write("DR status: " + dr.Status);
 
   // Only process if the status is "delivered"
   if (dr.Status == "Delivered")
   {
    // Try and update the database
    SqlConnection conn = new SqlConnection(
     "Data Source=DEVSQL;Initial Catalog=MobiforgeMessageDemo;Integrated
Security=true");
 
    SqlCommand cmd = new SqlCommand("usp_MarkMessageAsDelivered", conn);
                    cmd.CommandType = CommandType.StoredProcedure;
 
    // Make sure we set the aggregator message ID
    cmd.Parameters.Add(new SqlParameter("@AggregatorMessageID",
dr.SubmissionRef));
 
    conn.Open();
    cmd.ExecuteNonQuery();
    conn.Close();
 
    // Show we updated the database in the trace
    Trace.Write("Successfully updated database.");
   }
  
   // A different status has been received, so we output a message to show    
   // this
   else        
   {
   Response.Write("Message was not delivered. Status: " + dr.Status +
"<BR>");
   }
 
   // Write out a confirmation message at the end
   Response.Write("OK");
  }
}
catch (Exception ex)        // Output the error details
{
  Response.Write("Error occurred whilst processing: " + ex.Message);
  Trace.Write("Error occurred whilst processing: " + ex.Message);
}
}

The changes we’ll make are:

  • Add a class to represent an inbound SMS message
  • Add a method to inspect the POST data and determine whether a delivery receipt or inbound SMS message has been received
  • Move the delivery receipt processing into a separate method
  • Add a method to process an inbound SMS message
  • Change the Page_Load event to call the appropriate methods and process inbound requests

The Inbound SMS Message Class

The inbound SMS message class does nothing more than parse the inbound data from iTagg and convert it to properties on the class. This makes it easier for us to insert the message into the database.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
using System;
using System.Collections.Generic;
using System.Web;
 
/// <summary>
/// Summary description for InboundSmsMessage
/// </summary>
public class InboundSmsMessage
{
    private string _aggregatorMessageID = string.Empty;     //The aggregator message ID
    private string _originator = string.Empty;              // The message originator
    private string _recipient = string.Empty;               // The message recipient
    private DateTime _messageDate = DateTime.MinValue;      // Date/time the message was received
    private string _messageBody = string.Empty;             // The message body
 
    // Public accessors
    public string AggregatorMessageID
    {
        get { return _aggregatorMessageID; }
        set { _aggregatorMessageID = value; }
    }
 
    public string Originator
    {
        get { return _originator; }
        set { _originator = value; }
    }
 
    public string Recipient
    {
        get { return _recipient; }
        set { _recipient = value; }
    }
 
    public DateTime MessageDate
    {
        get { return _messageDate; }
        set { _messageDate = value; }
    }
 
    public string MessageBody
    {
        get { return _messageBody; }
        set { _messageBody = value; }
    }
 
    /// <summary>
    /// Accepts Input Stream parameter as a string and populates class properties
    /// </summary>
    /// <param name="InputStream"></param>
public InboundSmsMessage(string InputStream)
{
        // Obtain the parameter values by splitting on the ampersand
        string[] parameters = InputStream.Split(new char[] { '&' });
 
        // And now we can loop around the parameters and process each value
        // Note that we don't process every value iTagg send to us as we don't need them all
        for (int i = 0; i < parameters.Length; i++)
        {
            // Separate parameter name and value
            string[] parameterValues = parameters[i].Split(new char[] { '=' });
 
            // Should have two values
            if (parameterValues.Length == 2)
            {
                // Assign the value to the appropriate class property
                switch (parameterValues[0])
                {
                    case "source":
                        _originator = parameterValues[1];
                        break;
 
                    case "dest":
                        _recipient = parameterValues[1];
                        break;
 
                    case "dtime":
                        // Length should be 12
                        // 4 digits for YYYY
                        // 2 digits for MM
                        // 2 digits for DD
                        // 2 digits for HH
                        // 2 digits for MM
                        if (parameterValues[1].Length == 12)
                        {
                            int year = Convert.ToInt32(parameterValues[1].Substring(0, 4));
                            int month = Convert.ToInt32(parameterValues[1].Substring(4, 2));
                            int day = Convert.ToInt32(parameterValues[1].Substring(6, 2));
                            int hour = Convert.ToInt32(parameterValues[1].Substring(8, 2));
                            int minute = Convert.ToInt32(parameterValues[1].Substring(10, 2));
 
                            DateTime dateToProcess = new DateTime(year, month, day, hour, minute, 0);
                            _messageDate = dateToProcess;
                        }
                        break;
 
                    case "message":
                        _messageBody = parameterValues[1];
                        break;
 
                    case "message_id":
                        _aggregatorMessageID = parameterValues[1];
                        break;
                }
            }
        }
}
}

There’s not much to say about this code; it’s self-explanatory. In the real world we’d add try/catch blocks, constants for literal values, and better processing around dates.

POST Data Processing Method

The method to check if the POST data returns a Boolean – true if we’re processing a delivery receipt, false if we’re processing an inbound SMS message.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
    /// <summary>
    /// Determines whether we should process a delivery receipt or an inbound SMS message
    /// </summary>
    /// <param name="inputStream">The data to check</param>
    /// <returns></returns>
    private bool deliveryReceiptReceived(string inputStream)
    {
        // Assume we're processing an inbound SMS message
        bool deliveryReceiptReceived = false;
 
        // If the input stream contains a delivery receipt XML element,
        // return delivery receipt
        if (inputStream.Contains("itagg_delivery_receipt"))
        {
            deliveryReceiptReceived = true;
        }
 
        return deliveryReceiptReceived;
    }

We perform a simple check for a delivery receipt value, and if we find that value we know we’re processing a delivery receipt.

Move Delivery Receipt Processing Into a Separate Method

We now move the coding to process a delivery receipt from the Page_Load event into a separate method called, originally enough, processDeliveryReceipt.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
/// <summary>
    /// Process the inbound delivery receipt and add it to the database
    /// </summary>
    /// <param name="inputStream"></param>
    private void processDeliveryReceipt(string inputStream)
    {
        // Create a delivery receipt
        iTaggDeliveryRecipt dr =
            new iTaggDeliveryRecipt(inputStream);
 
        // Write out the delivery receipt details to the trace
        Trace.Write("iTagg DR data: " + inputStream);
 
        Trace.Write("DR submission ref: " + dr.SubmissionRef);
        Trace.Write("DR status: " + dr.Status);
 
        // Only process if the status is "delivered"
        if (dr.Status == "Delivered")
        {
            // Try and update the database
            SqlConnection conn = new SqlConnection(
                "Data Source=DEVSQL;Initial Catalog=MobiforgeMessageDemo;Integrated Security=true");
 
            SqlCommand cmd = new SqlCommand("usp_MarkMessageAsDelivered", conn);
            cmd.CommandType = CommandType.StoredProcedure;
 
            // Make sure we set the aggregator message ID
            cmd.Parameters.Add(new SqlParameter("@AggregatorMessageID", dr.SubmissionRef));
 
            conn.Open();
            cmd.ExecuteNonQuery();
            conn.Close();
 
            // Show we updated the database in the trace
            Trace.Write("Successfully updated database.");
        }
        else        // A different status has been received, so we output a message to show this
        {
            Response.Write("Message was not delivered. Status: " + dr.Status + "<BR>");
        }
 
        // Write out a confirmation message at the end
        Response.Write("OK");
    }

This method creates a delivery receipt object and inserts it into the database.

Add a Method to Process an Inbound SMS Message

Our penultimate step sees us write a similar method to that above, but to process an inbound SMS message.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
/// <summary>
    /// Processes an inbound SMS message and adds it to the database
    /// </summary>
    /// <param name="inputStream"></param>
    private void processInboundSmsMessage(string inputStream)
    {
        // Create an inbound SMS message
        InboundSmsMessage message = new InboundSmsMessage(inputStream);
 
        // Write out the SMS details to the trace
        Trace.Write("iTagg SMS data: " + inputStream);
 
        // Only process if we have valid data
        if (message.AggregatorMessageID != string.Empty)
        {
            SqlConnection conn = new SqlConnection(
                "Data Source=DEVSQL;Initial Catalog=MobiforgeMessageDemo;Integrated Security=true");
 
            SqlCommand cmd = new SqlCommand("usp_InsertMessage", conn);
            cmd.CommandType = CommandType.StoredProcedure;
 
            // Set the parameters
            cmd.Parameters.Add(new SqlParameter("@AggregatorMessageID", message.AggregatorMessageID));
            cmd.Parameters.Add(new SqlParameter("@InboundMessage", true));
            cmd.Parameters.Add(new SqlParameter("@Originator", message.Originator));
            cmd.Parameters.Add(new SqlParameter("@Recipient", message.Recipient));
            cmd.Parameters.Add(new SqlParameter("@MessageBody", message.MessageBody));
            cmd.Parameters.Add(new SqlParameter("@MessageDate", message.MessageDate));
 
            conn.Open();
            cmd.ExecuteNonQuery();
            conn.Close();
 
            // Show we updated the database in the trace
            Trace.Write("Successfully updated database.");
        }
 
        // Write out a confirmation message at the end
        Response.Write("OK");
    }

The InboundSmsMessage class takes care of parsing the input stream; once we have these values we write it to the database.

If we were following strict OOP guidelines we’d have put the database code in a method on the InboundSmsMessage class called Update(). We’d also have added a similar method to the Delivery Receipt class.

The Page_Load Event

All that’s left to do now is rewrite the Page_Load event to call the methods we’ve written.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
protected void Page_Load(object sender, EventArgs e)
    {
        try
        {
            // Check if some POST data was passed
            if (Request.InputStream != null)
            {
                StreamReader sr = new StreamReader(Request.InputStream);
 
                // Convert the POST stream to a string
                // We remove the xml= tag at the front, otherwise the XML will not parse
                // NOTE - "xml" is only passed if we receive a delivery receipt
                string inputStream = sr.ReadToEnd().Replace("xml=", string.Empty);
 
                if (deliveryReceiptReceived(inputStream))
                {
                    processDeliveryReceipt(inputStream);
                }
                else
                {
                    processInboundSmsMessage(inputStream);
                }
            }
        }
        catch (Exception ex)        // Output the error details
        {
            Response.Write("Error occurred whilst processing: " +
                            ex.Message);
            Trace.Write("Error occurred whilst processing: " +
                            ex.Message);
        }        
    }

This method has been greatly simplified. The first part remains the same – we convert the input stream to a string. After that, we check if we’ve received a delivery receipt and process accordingly.

We’re now ready to try it out!

Putting It All Together

Publish the listener to IIS and make sure you can access it through your Web browser. Once you’re happy visit iTagg (or your selected aggregator) and set up the URL as the inbound message path by either configuring it in the aggregator control panel, or contacting aggregator support.

Then try sending in a message. A typical message may look like:



Figure 3 About to send a message

Send this message, and after a few seconds it should appear in the Messages database table.



Figure 4 The updated Messages table

Summary

It’s not difficult to process inbound SMS messages – in fact, it’s quite similar to sending an inbound message. Once you have a simple database configured, it’s pretty easy to process the messages and insert them into the database. The main thing to consider is your choice of aggregator – as you’ll be tied in to their shortcode it’s vital you make the correct choice.

Our example system has some limitations. Firstly, we don’t actually do anything with the inbound message. A further article will show how to do this. Secondly, what we’ve developed can only support one keyword/shortcode. Say we have keyword1 on 60300 and keyword2 on 60300, and we wanted different messages to be sent back depending upon which keyword/shortcode was used. We’d need to add a Keywords table to the database and link this to the Messages table. We could then amend our stored procedures accordingly and change our class library and listener Web page over to process messages from different keywords. We’ll also look at how to do this in a future article.

Tagged in:
Design & Development, Messaging

Exclusive tips, how-tos, news and comment

Receive monthly updates on the world of mobile dev.

Other Products

Market leading device intelligence for the web, app and MNO ecosystems
DeviceAtlas - Device Intelligence

Real-time identification of fraudulent and misrepresented traffic
DeviceAssure - Device Verification

A free tool for developers, designers and marketers to test website performance
mobiReady - Evaluate your websites’ mobile readiness

© 2024 DeviceAtlas Limited. All rights reserved.

This is a website of DeviceAtlas Limited, a private company limited by shares, incorporated and registered in the Republic of Ireland with registered number 398040 and registered office at 6th Floor, 2 Grand Canal Square, Dublin 2, Ireland

All