Sending SMS messages using kannel - Rails

Sending SMS messages using kannel - Rails


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?

Getting started

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


Loading Gist

Visiting 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

visit the 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
# make install
password: **************

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 Huawei E173.

Configuration Files

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).


Loading Gist

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


Loading Gist

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.

Receiving Messages

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


Loading Gist

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 ( we should see our update successfully created

Your Done!

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.

Good luck!





Victor Areba

16 May 14

Just what I needed!



25 Jul 16

Hi Joseph, Great post. Wondering if you would be available for a couple questions on setting this up? I need a similar application here for my business but I'm just technical enough to be dangerous! Please ping me on Skype at crucible_67 and lets discuss a little project together

Latest Tutorials


Private Inbox System in Rails with Mailboxer New

Introduction It's been quite a while since my last tutorial and since then I've recieved alot of requests by email to implement a private messaging system ...

Ajax Sortable Lists Rails 4

With me, is a simple to-do list application where users can create dummy to-do lists and displays them in card-like form just like in Trello. We want to e...

Managing ENV variables in Rails

Often when developing Rails applications, you will find a need to setup a couple of environment variables to store secure information such as passwords, a...

Gmail Like Chat Application in Ruby on Rails

Introduction We are all fond of the Gmail and Facebook inline chat modules. About a week ago, I came across a tutorial on how to replicate hangouts chat...

Fast Autocomplete Search Terms - Rails

Introduction In many cases you find that you need to introduce a global search in your rails application i.e. search multiple models at a go using one form...

Load more scroll top