Sending SMS messages using kannel - Rails
16 May 14
In this tutorial, I will guide you on how to set up, configure and use Kannel to send and recieve messages from a ruby on rails web application. Hang tight!
I recently was tasked with setting up a web application in ruby on rails that interacted with users through SMS messages. While they are a number of solutions to handle this seamlessly e.g the famous
Twilio API , such solutions can prove a little costlier for most business startups as was in our case. I was looking for something cheaper which would achieve the same and thats when I came across Kannel.
Kannel is a compact and very powerful open source WAP and SMS gateway, used widely across the globe to serve trillions of short messages (SMS), WAP Push service indications and mobile internet connectivity. It also has the advantage of being open source and thus very, very free. The main use for Kannel is to link HTTP based services to various SMS centers using obscure protocols. With this it becomes very easy to integrate with web applications as they use HTTP protocols.
In this tutorial, I will try and explain from scratch, how to set up a simple rails application that interacts with users through SMS messages powered by Kannel. Our app will be simple, it will accept a users phone number and a status update, more like what you normally do on facebook. Quite easy huh?
As usual, lets start by creating a new rails application, lets name it sms
$ rails new sms
I will add bootstrap styling behind the scenes to achieve quick styling. Next, to get started fast and running, lets scaffold and update which will create the respective controllers, models and views. On your terminal
$ rails g scaffold update phone:string message:text
Next lets migrate the database and configure the root of our application to point to our index action of our updates controller
$ rake db:migrate
http://0.0.0.0:3000 we now have our updates page
Lets create our first update
Visiting our root path, we successfully created our first update
With our application now creating post through the web interface, lets power it with Kannel goodness so that posts can be created through SMS messages and the app can send a confirmation message when a post was successfull.
Setting, configuring, and using Kannel tends to be a nightmare for beginners but I will try to be as simple as possible. Most of the instructions here will work on any Unix platform, such as Linux (ubuntu, fedora, debian etc), FreeBSD, and or Mac OS X.
Downloading and Compiling
Kannel.org website and download the latest and greatest gateway-1.X.Y.tar.gz file. As of this posting, the latest gateway version is 1.5.0. After a successful download, as root
# tar xfz ../downloads/gateway-1.5.0.tar.gz
# cd gateway-1.5.0
# ./configure --prefix=/usr/local/kannel
We chose to install to
/usr/local/kannel to keep everything reasonably separated and organised. You’re free to put it anywhere. Lets now compiler and install
# make install
We need to set up some configuration files. This files have a myriad options to support all of the possible and powerful ways in which Kannel can be used. I will be showing strictly how I set it up for the
Still as root, navigate to our kannel's installation directory
/usr/local/kannel and create a file called smskannel.conf. This file is divided into a few key groups, each representing the key parts of the kannel system, including the server that handles sending and receving the actual SMSes (bearerbox) and the system that handles the final dispatching to your scripts (smsbox).
The group you should probably take note of is the
sms-service. This particular configuration has Kannel set up to use an HTTP POST request to send the message to our rails application. The param phone contains the phone number of the sender and the message parameter contains their entire message. This maps to the updates_path in our application.
NOTE: You can also configure the sms-service to send them as GET messages as well.
To read more details about waht each group does, I suggest you take a look at this
post. Next up, we included a modems.conf at the top of our smskannel configuration file. Kannel and smsc tends to be pretty good at figuring out everything about your modem by themselves, but you can help them out by including modems.conf in our smskannel.conf as we did.
Still as root create a
modems.conf configuration file in kannels installation directory. Add the following directives to it
Running the server
The hard part is done and all we have to do now is start the service up. Make sure you are in kannel's installation directory and start our first server i.e bearerbox which handles sending and receving the actual SMSes
# sbin/bearerbox -v 0 smskannel.conf
This will spoof alot of debug messages but eventually you should see a success messsage like the one below
On a new terminal, lets fire up our next server (smsbox) that handles the final dispatching to your scripts.
# sbin/smsbox -v 0 smskannel.conf
This should give you something similar to the screen below
Sending Messages through Kannel
With all our servers up and running lets give it a test drive by sending our first outgoing SMS messages through Kannel, this can be done via an HTTP interface. On your browser visit the following url
You should get an accepted for delivery response
0: Accepted for delivery
Wait a few seconds and you should have the message on your phone. Here's mine
Yaaay!!! this is when you pat yourself on your back ;-). You can always invoke this url from your app to send messages to users through a GET request.
Last part is recieving SMSes through sms. One gotcha is that rails will deny requests coming in from Kannel at they don't have the CSRF authenticity token that is required for each post request by rails. For our application will disable this check in our updates controller for our create action
In your updates controller add line 3 below
With that done lets reply our earlier message and see if it works
Observe both your consoles where we run our servers and you should see Kannel pick our sent message and dispatch it to our rails application
Now that look very promising. Refreshing our root path (
http://0.0.0.0:3000/) we should see our update successfully created
That’s pretty much it. I have tried as much to address every bit of the process, but it does contain everything you need to get Kannel. Kannels documentation has just about anything you could possibly want to know, so keep digging in there if you’re stuck. Have any questions? Let me know in the comments section below.