In the last decade, sending and receiving mobile phone text messages has gained significant popularity, as it is a very effective and reliable communication method. Wouldn’t it be fantastic to leverage this functionality in your own applications so you can communicate to your users using SMS messages? Fortunately, it is very easy to implement this into your own applications.
Choosing a gateway
In order to forward SMS messages to mobile handsets, a provider must be chosen that will take care of the forwarding to the network of mobile operators. A lot of providers offer this functionality, but often only offer an online portal or email to SMS options. For easy integration, we need a provider that offers a gateway (or API as it is often called) that is easy to use. The easiest gateways provide connectivity by means of HTTP calls.
One of the suitable companies that offer such a gateway is Silverstreet. They have worldwide coverage and their message prices are typically much lower than what you would pay if you use your own mobile phone with your own provider. Let’s look at their HTTP gateway and find out how to send text messages.
Sending your first message
A single text message just takes one HTTP call with some parameters. Firstly, the gateway needs to know which customer is requesting to send a message. Silverstreet will provide a username and password once you setup an account with them, and these credentials are needed to authenticate. Secondly, information about the actual message needs to be provided. A recipient, sender and a message body are minimally required. Here is an example of a valid request:
The above request will send a text message to phone number +1782236545 with sender +1782236544 having a message body of “test”. If the request is validated and processed successfully, the gateway responds with “01” indicating that everything went successfully.
Sending basic messages is great, but the fun doesn’t stop there. One of the most interesting features that are not available when sending text messages through a mobile handset is manipulating the sender. It is actually possible to provide an alphanumeric sender. Instead of a telephone number, you can use the branding of your application, e.g. sending messages with sender “WEBSHOP X”. Be careful though, because most mobile operators have an 11 character limit.
Another feature is changing the message payload from a normal text message to Unicode or Binary. This way you can send a non-latin text or even things like pictures and ringtones. These features are of course not supported on all handsets. Refer to the gateway documentation for a full range of options.
So you have been texting several users of your application, but how will you know if all of these messages successfully arrived at their destinations? Fortunately, all mobile handsets will acknowledge a received text message. This acknowledgment is commonly known as a delivery report. And this delivery report can be sent to a server of your choice by the SMS gateway.
When sending a text message over a gateway, we need to include two additional parameters. The first one is the indication that we are interested in a delivery report. Setting the DLR parameter to 1 takes care of this. The second parameter is called REFERENCE and contains a unique reference to identify the specific message. Here is an example of such a request:
In order to successfully receive a delivery report, a URL has to be provided to Silverstreet as a one-time action. Once this URL is configured, all requested delivery reports will automatically be delivered to that URL.
Let’s say your URL is this:
When a delivery report is received, this URL is called with the status of the delivery and the reference value that was submitted in the initial request:
The above example shows that a text message with reference 12345678 has been delivered to the handset.
For most basic uses this guide will be more than enough. If you require a high volume of messages or a very fast message throughput, an HTTP gateway might not be your best choice. If this is the case, it is better to investigate sending messages using the SMPP protocol. Coincidentally, Silverstreet also supports this type of connectivity.