There are many technologies and protocols that can be used to send and receive SMS from an application. This article focuses on sending SMS via a Short Message Service Center (SMSC), with the help of the Kannel SMS gateway.
In order for an application to send a SMS, it generally has to communicate with a Mobile Network Operator (MNO) over the Internet. To understand in more detail consider the following example.
A Media service provider wants to send a program timetable as an SMS to its end customers. The application is running on a Linux based java application server. One of the main requirements is to send an SMS through an SMSC, and this SMSC service is provided by one of the mobile network operators.
Before diving deeper into the subject, let’s go through some of the technical jargon.
SMSC: stands for the Short Message Service Center and is part of the telecommunications network to deliver the SMS. It enables the external application to integrate via the Internet.
- SMPP: stands for the Short Message Peer-to-Peer (SMPP) and it’s a protocol which is used to exchange the SMS between SMSC and external entities like business applications.
There are various versions of SMPP, including 3.3, 3.4 and 5.0. In this article version 3.4 is used. (Means the SMSC supports the version 3.4, more details from http://opensmpp.logica.com/
- Kannel SMS gateway it is an open source WAP and SMS gateway used to provide short message service (SMS). Currently it runs on the Linux platform and provides a high level HTTP service for submitting SMS requests. It supports many protocols to connect with the SMSC and even supports the GSM modem. (For more details see www.kannel.org)
Now back to our example
This media service provider wants to connect with the SMSC by using the SMPP protocol. Implementing the protocol takes some time, so why reinvent the wheel? Therefore the service provider plans to use the Kannel SMS gateway to connect with the SMSC. At the development phase it is important to test the SMSC integration, but most of the time it won’t be possible to test with the production SMSC and of course each SMS is an added cost. Therefore to test the integration an SMPP SMSC simulator will be used. From http://www.seleniumsoftware.com/downloads.html it's possible to download a free simulator. This simulator is a Java application and by default it will be running on port 2775. It is configurable from the property file SMPPSim/conf/smppsim.props.
Setting up the Kannel Server
Let’s now look into setting up the Kannel Server. Kannel is deployed on Linux systems (at the moment Windows platform is not supported; possibly using a virtual machine it could be run under Windows). Please be sure to include mysql support (or any other database support) when compiling the Kannel. It will be used to store the intermediate message between Kannel and SMSC specially the SMS delivery receipts.
Let’s assume, Kannel is deployed in /usr/local/kannel. Actually Kannel is a composed of 3 main components which are bearerbox, smsbox and wapbox. To run the Kannel, following 2 components must be started in a sequence.
/usr/local/kannel/sbin/bearerbox(This handles the connections with SMSC or gsm modem)/usr/local/kannel/sbin/smsbox(This provides an http service to send the SMS through the bearerbox)
First bearerbox should be started then smsbox should be started.
Both these boxes need a configuration file which contains the setting details. We’ll look into a sample configuration file (mytestkannel.conf). (More details can be retrieved from the Kannel documentation/user guide). This configuration file will have multiple sections; let’s go through the first section.
1. Configuring the core (bearerbox core)
group = core
admin-port = 6000
smsbox-port = 6001
admin-password = 'mysecrect'
dlr-storage = mysql
It has more properties such as allowed IP list and other security related settings. When running for production care should be taken to set it up appropriately for your application
dlr-storage = mysql means to store the intermediate process results in a table and read it back when its needed. When Kannel submits the SMS to the SMSC, then SMSC will return the results whether the SMS has been delivered or lost, or any other information as a delivery report back to the Kannel. This information will be stored in a database (according to the configuration it will be in MySQL) for an intermediate use and will be processed again when the application requests for a delivery report. It’s more reliable to use a database in the production, but for testing it could be set to dlr-storage = internal. Then kannel will store the results in memory and return it to the application when it’s requested via callback URL.
When using MySQL the following properties should be added in the configuration file.
#--- mysql connection
group = mysql-connection
id = mydlr
host = dbhost
username = user
password = secrect
database = kannelDb
max-connections = 1
#---- DLR table structure
group = dlr-db
id = mydlr
table = kannel_dlr
field-smsc = smsc
field-timestamp = timestamp
field-destination = destination
field-source = source
field-service = service
field-url = url
field-mask = mask
field-status = status
field-boxc-id = boxc_id
Table kannel_dlr will have field from SMSC to boxc_id. All these fields will have the datatype as varchar.
2. Connecting to the SMSC
Kannel bearerbox has to connect with the SMSC. Let’s look into setting up the SMSC. For testing we’ll be setting up with the SMSC simulator. When it ready for production, then we have to only change the IP address or port.
#---- This is connection to smpp simulater
group = smsc
smsc = smpp
smsc-id = testsmsc
host = test.host.com
port = 2775
receive-port = 2775
smsc-username = 'smppclient'
smsc-password = password
system-type = 'VMA'
service-type = 'test'
interface-version = 34
address-range = ''
msg-id-type = 0
Username and password can be changed in the SMPP SMSC simulator. (It can be done in SMPPSim/conf/smppsim.props).
Now we have set up Kannel to use the SMSC simulator.
3. Configuring the smsBox
In the same configuration file, we’ll be adding another section. This section will contain all the necessary details for the smsBox to run.
group = smsbox
bearerbox-host = test.host.com
sendsms-port = 6013
global-sender = 6013
We have to setup a user/password, which will be used to access the http service to submit the SMS. More details from the Kannel user guide.
group = sendsms-user
username = peter
password = ford
default-smsc = testsmsc
Starting the server
Now the entire configuration is done. Let’s fire up the engines. First start the SMPP SMSC simulator.
SMPPSim/startsmppsim.sh
Make sure Java path is setup. Ok. Simulator has started.
Next start the Kannel components in following order.
./bearerbox mytestkannel.conf
then
./smsbox mytestkannel.conf.
Ok. Kannel components have been started. Log files and console will display errors when they occur. Make sure to set the log level to "debug" when developing.
According to the SMPP protocol, client and the SMSC will be sending enquire_link messages to check whether either end are active. By default, Kannel will send this message every 30 second. Depending on the SMSC, it should be changed.
Now we write some simple Java code which is going to send the SMS. It will be using the HTTP GET method to submit the request.
|
1 2 3 4 5 6 |
StringBuffer param = new StringBuffer(); param.append('<a href="http://test.host.com:6013/cgi-bin/sendsms" target="_blank">http://test.host.com:6013/cgi-bin/sendsms</a>'); param.append('?username=peter'); param.append('&password=ford'); param.append('&from=').append('cust'); // any alphanumeric address param.append('&to=').append('47xxxxxx'); //mobile number which will receive the SMS |
Note that we can send normal text messages as well as binary messages. Binary message could be OTA configurations, WAP push, ringtones … etc. (See this article for more details on sending binary messages).
Let’s look at sending a normal text message message.
|
1 |
param.append('&text=').append( 'Hello mobile world'); |
When sending the binary message, remember to encode the message.
|
1 2 3 |
param.append('&udh=').append('%0B%05%04%0B%84%00%00%00%03%6E%03%01'); param.append('&text=').append('%01%06%2F%1F%'); //it could contain 256 chars param.append('&coding=').append('1'); //Its the DCS field and setting it to be 8bit binary message |
Now setting the delivery report callback URL:
|
1 2 3 4 5 6 7 |
param.append('&dlr-mask=').append('7'); //its a bit mask value or simply we can set it to 1 to receive the successful delivered SMS. param.append('&dlr-url=').append('http%3a%2f%2ftest%2ehost%2ecom%2fdlr%2fdlr%3ftype%3d%25d%26receiver%3d%25p%26reply%3d%25A%26time%3d%25t%26usr%3d%25n%26message%3d%25a'); //Its the encoded URL which informs the kannel that the delivery message should be submited to the following callback URL. //callback URL is <a href="http://test.host.com/dlr?type=%d&receiver=%p&reply=%A&time=%t&usr=%n&message=%b" target="_blank">http://test.host.com/dlr?type=%d&receiver=%p&reply=%A&time=%t&usr=%n&message=%b</a> //More information form the documentation System.out.println('Submit request=' + param.toString()); |
Sending the request:
|
1 2 3 4 5 6 7 8 9 10 |
URL aPortUrl = new URL(param.toString()); URLConnection con = aPortUrl.openConnection(); BufferedReader in = new BufferedReader( new InputStreamReader(con.getInputStream())); String inputLine; StringBuffer aResult = new StringBuffer(); while ((inputLine = in.readLine()) != null) aResult.append(inputLine); in.close(); System.out.println('; result=' + aResult.toString()); |
Now we have submitted the SMS request and the delivery receipt will be delivered by replacing the values in the callback URL. This callback URL is a Servlet which will simply get the parameter and value from the URL and logged it to a file or database for tracing purpose.
This is a just a scratch on the surface of Kannel, SMPP and SMSC. Hope it helps to start using these technologies.
3 Comments
Thanks for the tutorial, but when I’m trying to implement it, I’m getting the error when the text messages has the space character.
So how did the following code work ?
—>
param.append(‘&text=’).append( ‘Hello mobile world’);