Kannel API (emulation)

Einleitung

In dieser Anleitung zeigen wir Ihnen wie Sie unsere SMS API mit Ihrem Kannel Client nutzen können, um SMS über Kannel an uns zu schicken.

Wenn Sie bereits Kannel für Ihre SMPP Verbindungen nutzen, können Sie LOX24 ganz einfach als zusätzliche Anbindung hinzufügen. Es sind keine Änderungen an Kannel notwendig, lediglich die Konfiguration wird um LOX24 ergänzt.

Support: berlin@lox24.eu

API Key

Um mit Kannel SMS zu verschicken benötigen Sie den API-Key. In Ihrem Web-Account erstellen Sie einen Schlüssel vom Typ ‘Kannel API’. Gehen Sie in die “Einstellungen” -> “API Einstellungen” und klicken Sie auf den Button “API Key erstellen”. Der Name ist beliebig, als Version wählen Sie “Kannel API”.

Konfiguration

Sie haben zwei Möglichkeiten SMS mit Kannel zu verschicken:

• wir senden die Zustellberichte (DLR) direk an Sie zurück
• wir senden die Zustellberichte (DLR) an Kannel zurück, was diese dann wie von Ihren SMPP Verbindungen gewohnt an Sie weiterleitet

Hinweis: Mehr über die Zustellberichte (DLR) im Allgemeinen können Sie hier nachlesen:

• Offizielle Kannel Dokumentation
• LOX24 DLR Dokumentation

Zustellberichte direkt an Ihren Endpoint

Die LOX24 API wird die Zustellberichte ohne Umweg über Kannel direkt an die von Ihnen hinterlegte URL oder Mail Adresse senden.

Ergänzen Sie Ihre Kannel-Konfiguration wie folgt:

group = smsc
smsc = http
system-type = kannel
smsc-id = "lox24"
allowed-smsc-id = "lox24"
port = 10443
send-url = "https://lox24.eu/api/kannel/{SERVICE_CODE}.php"
smsc-username = "{USER_ID}"
smsc-password = "{API_KEY}"
max-sms-octets = 1530

Wobei:

• SERVICE_CODE - der Name des SMS Typs in Kleinbuchstaben, z.B. ‘text2speech’, ‘direct’ etc.
• USER_ID - Ihre Account ID (Kunden-Nr.), identisch mit der ID für den Login unter account.lox24.eu
• API_KEY - der API Schlüssel vom Typ ‘API Kannel’. Hier Können Sie sehen wir Sie diesen erstellen.

Zustellberichte zurück an Kannel

Wir senden die Zustellberichte zurück an Kannel. Kannel leitet diese dann wie von Ihnen konfiguriert an Sie weiter.

Ergänzen Sie Ihre Kannel-Konfiguration wie folgt:

  group = smsc
  smsc = http
  system-type = kannel
  smsc-id = "lox24"
  allowed-smsc-id = "lox24"
  port = 10443
  send-url = "https://lox24.eu/api/kannel/{SERVICE_CODE}.php"
  smsc-username = "{USER_ID}"
  smsc-password = "{API_KEY}"
  dlr-url = "http://youhosthere.com:10443/?username={USER_ID}&password={API_KEY}"
  connect-allow-ip = "127.0.0.1;213.133.127.70;116.203.64.153;85.10.245.*"
  max-sms-octets = 1530

Wobei:

• SERVICE_CODE - der Name des SMS Typs in Kleinbuchstaben, z.B. ‘text2speech’, ‘direct’ etc.
• USER_ID - Ihre Account ID (Kunden-Nr.), identisch mit der ID für den Login unter account.lox24.eu
• API_KEY - der API Schlüssel vom Typ ‘API Kannel’. Hier Können Sie sehen wir Sie diesen erstellen.
• yourhostthere.com:10443 - Die Web-Adresse Ihres Kannel Clients ist.

Weitere Hinweise

LOX24 Zustellberichte

Falls Sie in den API-Einstellungen einen API v2 Status URL/E-mail Endpoint im Web-Account konfiguriert haben, können Sie auf dlr-url verzichten und die Zustellberichte in der gleichen Form erhalten wie bei einer normalen SMS über unsere API v2. Mehr hierzu hier.

SMSC port

Im Konfigurationsbeispiel haben wir den Port 10443 genutzt. Sie können aber jeden beliebigen Port nutzen. Wir empfehlen Ihnen Ihre Firewall entsprechend zu konfigurieren, um nur Anfragen des LOX24 SMS Servers zuzulassen (116.203.64.153,213.133.127.70,85.10.245.*).

Unterstützte Variablen DLR Url

Die LOX24 Kannel API unterstüzt für die DLR Url die folgenden Variablen:

• %d - Kannel report type (integer):

  • 1: Delivered to phone
  • 2: Non-Delivered to Phone
  • 4: Queued on SMSC
  • 8: Delivered to SMSC
  • 16: Non-Delivered to SMSC

• %q - Die international Rufnummer (E.164), welche die Nachricht erhält.

• %T - Die Uhrzeit des Zustellberichts als Unix Timestamp.

Hinweis: Sie können weitere Variablen verwenden, wir garantieren aber nicht die ordnungsgemäße Funktionsweise.

Parameter

from

(required)

Die Absenderkennung der Nachricht kann eine Rufnummer mit bis zu 15 Ziffern oder einen Text mit bis zu 11 Zeichen enthalten. Im Fall einer Rufnummer als Absender, halten Sie sich bitte möglichst an das E.164 Format. Ein Text Absender kann Leerzeichen enhalten, aber keine anderen Sonderzeichen, Umlaute oder Satzzeichen. Bitte beachten Sie, dass der Absender nicht in jedem Zielland übertragen werden kann und teilweise die Registrierung einer Absenderkennung durch lokale Regulierung erforderlich ist.

to

(required)

Zielrufnummer (international)

text

(required)

Der Nachrichtentext kann eine Länge von maximal 1530 Zeichen im GSM Standardzeichensatz enthalten. Mit einer Unicode SMS liegt die maximale Zeichenlänge bei 670 Zeichen. Das interne Encoding ist in beiden Fällen UTF-8.

coding

(optional)

Sie können SMS mit dem Parameter ‘coding’ verschicken:

0 - GSM 03.38 (default), 1 - 8-bit or 2 - UCS-2 encoding.

Wir verarbeiten 8-bit und UCS-2 identisch als Unicode SMS.

dlr-url

(optional)

Geben Sie eine URL an, an welche Sie die Zustellberichte von Kannel gesendet bekommen möchten. Falls Sie den Parameter nicht übergeben, nutzen wir den API v2 DLR endpoint Ihrer API Konfiguration (falls vorhanden).

deferred

(optional)

Können Sie nutzen, um die SMS zeitversetzt in der Zukunft zu verschicken. Die Angabe erfolgt in Minuten. Falls der Wert leer bleibt, wird die SMS sofort verschickt.

Beispiel request

Dieses Beispiel zeigt, wie Sie eine SMS an Ihre Kannel Installtion senden können. Die smsbox ist in diesem Beispiel auf dem lokalen Server und Port 9001.

http://127.0.0.1:9001/cgi-bin/sendsms?dlr-url=http://yourhost.com/dlr_test.php?status=%d%26time=%T%26q=%q%26customid=1234567&from=sender&password=test1&smsc=lox24&text=test%20message&to=+49751234567&username=test1&coding=0

Empfehlung

Ergänzen Sie die DLR url mit einem individuellen Parameter für Ihre eigene Message-ID, in unserem Beispiel ist dies customid = 1234567.