Die Global SMS API zum Senden und Empfangen von Kurznachrichten kann auf verschiedene Arten genutzte werden. Letztendlich mündet dann zwar alles meist in JSON/XML über REST, aber wer das nicht mag, kann dank der Developer Garden SDKs vorbereitete Bibliotheken nutzen. Diverse Programmierwelten werden unterstützt, darunter Java, .NET, PHP, Objective-C und Python. Diese Bibliotheken verstecken auch viel Komplexität – beispielsweise die Abläufe bei der Authentifizierung – und erleichtern so den Einstieg. Außerdem hilft der bereitgestellte Quellcode, die Funktionsweise der API besser zu verstehen, möchte man doch einmal Low-level direkt mit der RESTful API arbeiten.
Download und Doku
Die SDKs sowie die Dokumentation stehen im Developer Garden zum Download bereit.
Natürlich ist der letzte Stand der Dokumentation als HTML dort auch online einsehbar.
Ein kleiner Tipp am Rande: Die Global SMS API folgt einem Anbieter-übergreifenden Standard namens One API der GSM Association. Bei der GSMA handelt es sich um die 1987 gegründete Industrievereinigung der GSM-Mobilfunkanbieter mit mittlerweile mehr als 800 Mobilfunkanbieter. Dort ist unter http://www.gsma.com/oneapi/sms-restful-netapi auch eine weitere hilfreiche Dokumentation zum Thema SMS API erhältlich.
Nachdem die Entscheidung für ein SDK gefallen ist (hier in diesem Beispiel .Net) muss die darin enthaltene Funktionalität noch bereitgestellt werden. Da sich im SDK der Quellcode befindet, kann wahlweise dieser eingebunden oder eine Bibliothek erzeugt werden. So oder so muss unter Windows das heruntergeladene ZIP-Archiv noch entsperrt (dies gelingt am leichtesten über das Kontextmenü der Datei im Bereich Eigenschaften) und entpackt werden.
Einmal entpackt, kann nun der Quellcode, der auch zahlreiche Beispiele umfasst, eingesehen werden. Die relevante Projektmappe (Solution) für die Bearbeitung mit Visual Studio ist Telekom.sln.
Falls man in seine eigenen Projekte nicht immer den ganzen Quellcode einbinden möchte, kann nun innerhalb von Visual Studio die Bibliothek (DLL) erstellt werden, indem man das Projekt einmal „baut“ (Menü Build -> Build Solution). Standardmäßig findet sich die fertige Bibliothek dann im Quellcodeverzeichnis unter src/Telekom/bin/Debug. Neben der Telekom.dll liegt dort die ebenfalls notwendige Bibliothek Newtonsoft.Json.dll für die Verarbeitung von JSON.
Aktivierung und Zugangsdaten
Doch bevor es nun ans Programmieren einer eigenen Anwendung geht, muss man sich erst einmal im Developer Garden anmelden und die Global SMS API aktivieren.
Letzteres gelingt nach erfolgreicher Anmeldung durch Klick auf „Mein Konto“ und die anschließende Aktivierung von Global SMS API innerhalb der API-Verwaltung. Hier werden übrigens auch die Rufnummern für den Versand und Empfang verwaltet.
In der Applikationsverwaltung wird nun – als letzter Schritt bevor es an die Programmierung geht – eine neue Applikation erstellt und dort die Global SMS API verfügbar gemacht.
Hier finden sich auch die für die Nutzung der API wichtigen Angaben Scope, Client ID und Sicherheitstoken. Für die Programmierung werden diese unbedingt gebraucht.
Programmierung
Die Nutzung der Global SMS API ist wie hier in einer WPF Anwendung (oder sonst einem Anwendungstypen aus der .Net-Welt wie z. B. Windows Forms) nun sehr einfach. Alles was wir dafür brauchen sind die Bibliotheken und die Nutzungsdaten (Scope, Client ID und Sicherheitstoken).
Als erstes füge n wir die beiden Bibliotheken Telekom.dll und Newtonsoft.Json.dll dem Projekt hinzu. Sollte die Datei Telekom.dll sich nicht im SDK-Verzeichnis unter src/Telekom/bin/Debug finden, dann muss diese wie oben beschrieben noch erzeugt werden.
Nun legen wir eine Klasse mit den Nutzungsdaten an, um Zugriff auf die API zu erhalten. Die Nutzungsdaten finden sich wie oben beschreiben für jede Anwendung innerhalb Ihres Developer Garden Kontos (My Account) in der Applikationsverwaltung unter https://www.developergarden.com/my-account/application-management/.
Als nächstes legen wir ein Interaktionselement fest, das den SMS-Versand auslöst. Hier eine Schaltfläche, die durch Klicken die notwendigen Befehle startet.
Innerhalb der Ereignismethode für die Schaltfläche wird zuerst die Authentifizierung unter Angabe der Nutzungsdaten durchgeführt:
1
2
| TelekomOAuth2Auth authentication = new TelekomOAuth2Auth(Credentials.CLIENT_ID, Credentials.CLIENT_SECRET, Credentials.SCOPE);
authentication.RequestAccessToken(); |
TelekomOAuth2Auth authentication = new TelekomOAuth2Auth(Credentials.CLIENT_ID, Credentials.CLIENT_SECRET, Credentials.SCOPE);
authentication.RequestAccessToken();
Als nächstes müssen die Parameter für die SMS festgelegt werden. Darunter die Rufnummer des oder der Empfänger als Liste, die eigentliche Nachricht und die Absenderadresse – sofern noch keine validierte Rufnummer verfügbar ist, kommt als Absender 0191011 zum Einsatz. Andernfalls die gewünschte Rufnummer, diese dann aber mit dem Prefix „tel:“:
1
2
3
4
5
6
| List receiverNumbers = new List();
receiverNumbers.Add("tel:+4915112345678");
SendSmsRequest request = new SendSmsRequest();
request.Numbers = receiverNumbers;
request.Message = "Developer Garden rocks!";
request.SenderAddress = "0191011"; |
List receiverNumbers = new List();
receiverNumbers.Add("tel:+4915112345678");
SendSmsRequest request = new SendSmsRequest();
request.Numbers = receiverNumbers;
request.Message = "Developer Garden rocks!";
request.SenderAddress = "0191011";
Und im letzten Schritt wird die API noch aufgerufen (in diesem Beispiel durch einen synchronen Aufruf, es kann aber auch asynchron gearbeitet werden). Die Angabe ServiceEnvironment.Sandbox steht übrigens für die kostenlose aber auf 10 SMS am Tag beschränkte Nutzung:
1
2
| SendSmsClient client = new SendSmsClient(authentication, ServiceEnvironment.Sandbox);
SmsResponse response = client.SendSms(request); |
SendSmsClient client = new SendSmsClient(authentication, ServiceEnvironment.Sandbox);
SmsResponse response = client.SendSms(request);
In der Code-Behind-Datei legen wir noch die notwendigen Usings zum Einbinden der Namensräume fest, sofern das nicht bereits automatisch geschehen ist:
1
2
3
4
5
6
| using System.Collections.Generic;
using Telekom.Common;
using Telekom.Common.Auth;
using Telekom.Common.Model;
using Telekom.SendSms;
using Telekom.SendSms.Model; |
using System.Collections.Generic;
using Telekom.Common;
using Telekom.Common.Auth;
using Telekom.Common.Model;
using Telekom.SendSms;
using Telekom.SendSms.Model;
Das war es soweit. Starten der Anwendung und das anschließende Klicken auf die Schaltfläche sollte nun eine SMS versenden. Sofern wie in der Abbildung ein Unterbrechungspunkt gesetzt und der Debugger aktiv ist, kann man auch den erfolgreiche Aufruf der API sehen. Übrigens gibt es im Developer Garden auch ein Forum für Ideen und Fragen zum Thema. Viel Spaß…