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.

Configuration

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 variables:

  • charset We support Windows-1252, UTF-8 and UTF-16BE
  • coding You can send an SMS with GSM-7 (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 phone number

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 Kannel’s 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, i.e. 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, if perhaps you have a 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 the username and password is the same as in the Config above. And {gatewayapi_ip} is the IP that GatewayAPI uses for external communication.

Caveats

Long senders

Our Kannel API does some basic checks on the sender received via the from field. This check validates that the sender can actually be submitted via an SMPP connection. See SMS Sender for more information.

This behavior is different from the regular Kannel API, where long senders are accepted, but handling of those depends on the SMPP server in charge of further delivery. Actual validation of the sender is dependent on the SMSC that Kannel sends the message to, which means that the message could be rejected, have the sender modified to fit within the limitations or perhaps even just overwritten.

Actually validating the sender provides the most consistent integration.

Concatenated SMS

In order to support concatenated SMS, make sure to set the smsbox config variable 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 own 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 your Kannel setup. We really appreciate feedback, so please contact us via the live chat, especially if you have an urgent situation.