Skip to content

Kannel API

For this API you need a set of credentials. These are different from the OAuth API the Rest API uses. You can find them in the dashboard, under “API”.

We use the term Kannel API, because this is an API designed specifically for the Open Source Kannel SMS Gateway. It uses the Kannel-HTTPS-Kannel interface, which we re-implemented in GatewayAPI based on the Kannel source code.

Config

To use the API simply set up a new Kannel SMSC:

1
2
3
4
5
6
7
8
group = smsc
smsc = https
system-type = kannel
smsc-id = oc
port = 13019
send-url = "https://gatewayapi.com/kannel/sendsms/standard"
smsc-username = "{YOUR CREDENTIAL USERNAME}"
smsc-password = "{YOUR CREDENTIAL PASSWORD}"

The last path fragment is the message class to use. In this example set to standard

The important part is that you set the system-type to kannel, which tells Kannel to use its own protocol for this SMSC.

Features

Our kannel API is (almost) fully featured. The implemented features are listed below with their variable.

  • charset We support Windows-1252, UTF-8 and UTF-16BE.
  • coding You can send an SMS with GSM 03.38 (default), 8-bit or UCS-2 encoding.
  • dlr-url Specify a URL and have us call it with delivery status reports.
  • validity Have the SMS expire X minutes from now, if not delivered before it will be discarded.
  • deferred Have the SMS delivered X minutes in the future.
  • mclass Send an SMS as flash SMS, to display on the screen directly.
  • account Account name or number to enable tracing in your own systems. Will be set in userref.
  • udh You may specify your UDH and optionally binary SMS body for full control.
  • from You may set an alphanumeric sender max 11 chars, or up to 15 digits for a phonenumber.

The only feature we do not support yet is MWI (message waiting indicator). If you have a good use case for this feature, let us know in the live chat, and we will add it to the feature request tracker.

Delivery Reports

If you are not already an expert on Kannels status reports, take a brief look at Chapter 10 SMS Delivery Reports.

You are expected to provide a URL that contains one or more variables, which kannel then replaces with data. Especially %d which return the report type or status code.

Variables

  • %d Kannel report type, ie. 1 for delivered.
  • %A The answer of the SMSC. The format is {status}/{error_code} where error_code can be empty.
  • %p The MSISDN of the phone that received the message.
  • %q The international phone number (E.164), that received the message.
  • %T The time of the delivery report expressed as seconds since unix epoch.
  • %F The SMS ID used on GatewayAPI.com to track the message.
  • %o The userref/account for this SMS if specified.

DLR URL Chaining

Most commonly, you will have to provide the dlr-url to your Kannel server, when you send an SMS using the /cgi-bin/sendsms interface. Then as the final destination we will call your URL and not your Kannel server. However if this is not what you want, maybe you have firewall blocking it, you can have us call your Kannel server, which will then forward or chain the DLR to your server as if your Kannel server was the final destination. This is thoroughly detailed in the Kannel source code.

Should you have the need for Kannel to receive the DLR and then forward it to you as “normal” then add this to your config:

1
2
dlr-url = "https://{your_ip}/?username=SAME_AS_SMSC&password=SAME_AS_SMSC"
connect-allow-ip = {gatewayapi_ip}

You would have to fill in the IP placeholders, {your_ip} needs to be a public IP where we can reach your Kannel instance, make sure username and password is the same as in the Config above. And {gatewayapi_ip} is the IP GatewayAPI uses for external communication.

Caveats

Concatenated SMS

In order to support concatenated SMS, make sure to set the smsbox config var sms-length to something more than the default 140. Kannel will then split long SMS messages into several parts and set a UDH to allow the end user device to concatenate them together. Unfortunately Kannel insists on doing this on its end, so in the GatewayAPI traffic log it is going to show each segment separately.

Feedback is Appreciated

Although the Kannel API is tested extensively, it might not exactly fit you Kannel setup. We really appreciate feedback so please contact us via the live chat, especially if you have an urgent situation.