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.
To use the API simply set up a new Kannel SMSC:
1 2 3 4 5 6 7 8
The last path fragment is the message class to use. In this example set to
The important part is that you set the
kannel, which tells Kannel to use its own protocol for this SMSC.
Our kannel API is (almost) fully featured. The implemented features are listed below with their variable.
charsetWe support Windows-1252, UTF-8 and UTF-16BE.
codingYou can send a SMS with GSM 03.38 (default), 8-bit or UCS-2 encoding.
dlr-urlSpecify an URL and have us call it with delivery status reports.
validityHave the SMS expire X minutes from now, so if not delivered will be discarded.
deferredHave the SMS delivered X minutes in the future.
mclassSend a SMS to the ie. screen directly. Aka flash SMS.
accountAccount name or number to enable tracing in your own systems. Will be set in userref.
udhYou may specify your udh and optionally binary SMS body for full control.
fromYou 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.
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, which contains one or more variables which kannel then replaces with data. Especially
%d which gives back the report type or
%dKannel report type, ie. 1 for delivered.
%AThe answer of the SMSC. We give an answer in the form
%pThe MSISDN of the phone who received the message.
%qThe international phone number (E.164), who received the message.
%TThe time of the delivery report expressed as seconds since unix epoch.
%FThe SMS ID used on GatewayAPI.com to track the message.
%oThe userref/account for this SMS if specified.
DLR URL Chaining¶
The normal behavior is for you 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 explained in some length in the Kannel source code.
Should you have a need for kannel to receive the DLR and then forward it to you as “normal” then add this to your config:
You would have to replace the IP with a public IP where we can reach your server. Also make sure username and password is the same as in the Config above.
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 SMSes into several parts and set an 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.
This is a brand new API and although it is tested extensively, it might not exactly fit your kannel setup. We really appreciate feedback on this API. Please contact us via the livechat, especially if you have an urgent situation.