June 14, 2016 – Tech

Bringing Kannel APIs into the 21st Century

Recently, we’ve had a large influx of new customers running the open source Kannel SMS gateway, and from this, it has became apparent that we needed to design an API endpoint optimised specifically for Kannel. This post addresses the ‘what’, ‘why’ and ‘how’ that makes our API so different from your typical Kannel integration.

What

A brief look at Kannel’s 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.IO 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, SMPPC combined with a super 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 an SMPP endpoint, like so many of our competitors do. However, there are 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, 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 moment came when we realised 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 an HTTP(S) based API which was compatible with all the quirks of Kannel’s HTTP parsing which meant long nights reading Kannel’s source code and writing unit tests (because you really can’t rely on Kannel’s 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 specified 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 us know.

Global SMS Gateway

GatewayAPI has some of the lowest prices in the majority of the world combined with an intuitive interface, world class support and a rock-solid uptime of 99.99 % in average. If you don’t have an account yet, you can create a free account in less than two minutes here: Go to GatewayAPI or contact sales@gatewayapi.com

If you have a concept or business that could benefit from employing SMS communication, then don’t hesitate to contact us. We will help you get started.