As we had a large influx of new customers running the open source kannel sms gateway, it became apparent that we needed to design an API endpoint optimized specifically for kannel. This post dwells a bit on the ‘what’, ‘why’ and ‘how’ that makes our API different than your typical kannel integration.

What

A brief look at kannel history

Kannel is one of the most popular open source SMS gateways out there. Its development goes back to 1999, by coincidence the same year as our company OnlineCity started. The last release (1.4.4) was in Aug 2014.

Kannel commits to date, by year-month.

One of the reasons for its popularity is its ability to provide a gateway between complicated and wildly different APIs used by the mobile networks such as Nokia CIMD, CMG UCP/EMI, SMPP, and a dead simple HTTP interface for the developer.

Of course all that complexity adds up and kannel is comprised of nearly 300K lines of (mostly) monolithic C-code.

Why

SMPP does not fit all

SMPP is a nearly ubiquitous protocol for sending (bulk) SMS, with the most popular version specified in 1999 by the now disbanded SMS Forum.

We could have implemented SMPP and let kannel connect to a SMPP endpoint, like so many of our competitors do. However there is a few problems with this mostly related to security and scalability.

SMPP is a compact binary protocol, which is great for bandwidth and performance. However it also keeps one or more TCP sockets constantly connected to the SMSC, which is bad for scalability, load balancing and failovers.

Worse, SMPP does not provide any transport level security, such as SSL/TLS, and sends all your data including credentials as cleartext. So it needs to be layered with third party software like stunnel, vpn etc.

What’s needed is a solution designed in the 21st century and not the 20th.

Enter HTTPS

What we wanted to use is HTTP. It’s easy to scale using existing tools, HTTPS is encrypted with SSL/TLS and it’s pretty good at connection management no matter how many customers we get.

Kannel supports HTTP via its “generic” SMSC type, however it’s complicated to configure and once you delve into the edge cases it’s also limited compared to the other SMSC types.

The eureka came when we realized kannel also had a system type called “kannel”, which is meant for chaining kannel servers together. It’s HTTP(S) based and supports all the features the developer expects of kannel, so it’s a very good fit for us.

What remained was to implement a HTTP(S) based API which was compatible with all the quirks of kannels HTTP parsing etc, which meant long nights reading Kannel’s source code and writing unit tests. Because you really can’t rely on the kannel documentation if you want to be sure.

How

Since our API is compatible with kannel itself we can keep the config short.

Example config

group = smsc
smsc = http
system-type = kannel
smsc-id = gwapi
port = 13019
send-url = "https://gatewayapi.com/kannel/sendsms/bulk"
smsc-username = "{YOUR CREDENTIAL USERNAME}"
smsc-password = "{YOUR CREDENTIAL PASSWORD}"

Config explained

group = smsc
smsc = http
system-type = kannel

These set up the smsc protocol and system type.

smsc-id = gwapi
port = 13019

The SMSC ID is for tracking purposes, or if you use multiple providers in kannel. The port is where kannel will listen for incoming DLRs, which is generally not used unless your final DLR callback urls are not accessible from the internet. Because our gateway will deliver DLRs directly to the URL you provide to kannel. For more on receiving DLR / status reports, see our documentation.

send-url = "https://gatewayapi.com/kannel/sendsms/bulk"
smsc-username = "{YOUR CREDENTIAL USERNAME}"
smsc-password = "{YOUR CREDENTIAL PASSWORD}"

The send-url includes the message class to use, here spcified as “bulk”. Also you need to fill in “smsc-username” / “smsc-password”. The values for these are not your login info to gatewayapi.com/app/ - but a set of “Credentials”, which you must generate under “Credentials (deprecated)”, “Add Credentials”.

If you have any questions or comments to our APIs please use the live chat function and let is know.