SMS per HTTP versenden
HTTP/S-API-Dokumentation - Stand 12.5.2011
Sie sind Entwickler und möchten SMS-Versand auch in Ihre eigene
Webapplikation oder Webpräsenz (Homepage) integrieren? Kein Problem: Wir bieten
Ihnen hierfür ein unkompliziertes HTTP/S-Interface, auf welches Sie problemlos
zugreifen können.
 Einführung
 Das HTTP/S-API von 5CentSMS erlaubt das Verschicken von SMS
und SMS-Kontoabfragen über simple
HTTP/S-Aufrufe. Der SMS-Versand kann also mit Leichtigkeit in Ihre bereits
bestehenden Web-Applikationen, Web-Präsenzen und Skripte integriert werden.
Ein HTTP/S-Aufruf gliedert sich wie üblich in die Web-Adresse unseres HTTP/S-APIs und die durch
ein "?" getrennt angehängten Parameter. Die Parameter enthalten
Informationen wie Authentifizierung, Absender- und Empfängerkennung sowie den
SMS-Text.
Ein Beispiel:
-
http://5centsms.com/api/http/send/?user=u&pass=p&to=123&text=Hallo!
Eine SMS per HTTP/S-API versenden
Folgende Parameter werden zum Versenden einer SMS benötigt:
-
Authentifizierung:
Hierfür stehen die Parameter user und
pass, die sich auf die gleichen Angaben beziehen,
wie in der 5CentSMS-Software auf der Seite Konto. Geben Sie für
user also die Email-Adresse an, unter der Ihr
5CentSMS-Konto geführt wird. Für pass ist das
zugehörige Passwort einzusetzen.
-
Absenderkennung:
Die gewünschte Absenderkennung übergeben Sie im Parameter
from. Hierbei kann es sich um eine Telefonnummer handeln (max. 16
Zeichen) oder eine alphanumersiche Angabe (max. 11 Zeichen). Soll keine eigene
Absenderkennung verwendet werden, so lassen Sie diesen Parameter beim Aufruf
einfach weg oder benutzten Sie (ohne).
Damit der Empfänger ggf. auf Ihre SMS antworten kann, muss die verwendete
Telefonnummer im internationalen Format vorliegen. Für beispielsweise eine
deutsche Mobilfunknummer, die mit 0170... beginnt, ist also 49 für Deutschland
anstelle der 0 einzufügen: 49170... (Ein vorangestelltes "+"-Zeichen ist nicht
nötig). Für andere Länder gilt entsprechendes.
Sofern eine alphanumersiche Kennung verwendet wird, sollte diese URL-kodiert
übergeben werden, um Übertragungsprobleme zu vermeiden.
-
Empfängerkennung:
Die Mobilfunknummer des Empfängers übergeben Sie im Parameter
to (max. 16 Zeichen). Übergeben Sie die Zielnummer
möglichst im internationalen Format (siehe Hinweise bez. Absenderkennung).
Bei Verwendung einer nationalen Nummer (eine 0 am Anfang) geht das System von
einem Empfänger in Deutschland aus und liefert in das entsprechende Netz.
-
SMS-Text:
Den SMS-Text selbst setzen Sie in den Parameter text.
Der Text sollte unbedingt URL-kodiert übergeben werden, da es sonst zu
Übertragungsproblemen kommen kann. Sollte der Text länger als 160 Zeichen sein,
so wird er automatisch in mehrere Teilstücke zu maximal 153 Zeichen
aufgebrochen verschickt.
-
Empfangsbestätigung:
Optional können Sie sich den Empfang Ihrer SMS vom HTTP/S-API bestätigen
lassen. Der betreffende Parameter heißt ack (Acknowledge)
und erlaubt folgende Werte:
Kompletter Aufbau des SMS-Sendebefehls
Bei nachfolgend gezeigtem Beispiel werden user
und pass mit uuuu und
pppp belegt. Die Absenderkennung
from und Empfängernummer to
sind auf 88888888 und
999999999 eingestellt. Der SMS-Text text
lautet Nachricht.
-
Die SMS-Versand-URL zum HTTP-API heißt:
http://5centsms.com/api/http/send/
-
Für den SSL-gesicherten Versand über HTTPS benutzten Sie:
https://5centsms.com/api/http/send/
Hier nun ein komplettes Beispiel - bitte beachten Sie das "?" zwischen der URL und dem Parameterbeginn (Es handelt
sich um einen EINzeiligen Aufruf, der hier jedoch umbrochen dargestellt ist):
-
https://5centsms.com/api/http/send/?user=uuuu&pass=pppp&
from=88888888&to=999999999&text=Nachricht&ack=1
Rückgabewerte des SMS-Sendebefehls
Die Antworten auf Ihren Sendebefehl erhalten Sie in einer Kombination aus einem numerischen und verbalen
Ergebniscode, beide getrennt durch ein Semikolon. Geht der Versand glatt so
erhalten Sie z.B. 0;OK. Wurde dagegen eine
ungültige Zielnummer angegeben, so meldet der Aufruf
1;error sending sms. Und bei falscher Authentifizierung erscheint
999;access denied.
Beispielaufrufe für das Senden von
SMS über das HTTP/S-API
Die folgenden Beispiele sind klickbar und liefern je nach Aufbau einen der
o.g. Rückgabewerte (Es handelt sich bei allen um EINzeilige Aufrufe, der hier
jedoch umbrochen dargestellt sind):
Abfrage des SMS-Kontostands per
HTTP/S-API
Folgende Parameter werden zur Kontoabfrage benötigt:
-
Authentifizierung:
Hierfür stehen wiederum die Parameter user und
pass, die sich auf die gleichen Angaben beziehen,
wie in der 5CentSMS-Software auf der Seite Konto. Geben Sie für
user also die Email-Adresse an, unter der Ihr
5CentSMS-Konto geführt wird. Für pass ist das
zugehörige Passwort einzusetzen.
Kompletter Aufbau der
SMS-Kontoabfrage
Bei den folgenden Beispielen werden user
und pass wiederum mit uuuu und
pppp belegt:
-
Die Kontoabfrage per HTTP-API:
https://5centsms.com/api/http/balance/?user=uuuu&pass=pppp
Rückgabewerte der SMS-Kontoabfrage
Auch bei dieser Abfrage erhalten Sie ein kombiniertes Ergebnis aus zwei Werten,
getrennt durch ein Semikolon. Sofern die Parameter user und
pass korrekt angegeben wurden, erhalten Sie eine
Antwort vom Format 0;zahl. Die
0 zu Beginn signalisiert eine korrekte Abfrage, der Wert
zahl stellt den aktuellen Kontostand dar. Dies ist eine Fließkommazahl
wie z.B. 123,5. Falls die Authentifizierung nicht
gelang, so erscheint
999;access denied.
Skript-Beispiel: SMS per Formular mit PHP
verschicken
 Im folgenden Beispiel stellen wir Ihnen ein kleines, funktionierendes
Web-Interface zum Versenden von SMS mit 5CentSMS vor. Es besteht aus einem
Formular, über das Sie die Eingaben für die notwendigen Parameter machen. Für
den Versand (wahlweise HTTP oder HTTPS) sorgt ein kurzes PHP-Skript, in dem
alle in dieser Dokumentation besprochenen API-Funktionen zur Anwendung kommen:
(Die Liste der Skript-Beispiele wird in Kürze fortgesetzt
...)
Offene Fragen?
Die beantworten Ihnen gerne der 5CentSMS-Support per Email oder Telefon
(Kontaktdaten anzeigen).
|
|
