Receiving SMS Messages via Shortcodes & Keywords

Back around 1998, more and more billboards started to display some odd messages, along the lines of “Visit us on the web at”. 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:

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:

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.

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.

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.

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.

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.

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


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.

Other Afilias Products

Try the world’s leading device detection solution at
DeviceAtlas - Try the world’s leading mobile device detection solution

Create amazing web presences on any screen with
goMobi - Create amazing web presences on any screen.

Evaluate your websites’ mobile readiness with
mobiReady - Evaluate your websites’ mobile readiness.

© 2016 Afilias Technologies Ltd. All rights reserved.

This is a website of Afilias Technologies Ltd, 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