<< Zurück zu SMSout.de

SMS in eigenen Anwendungen erstellen und versenden (SMS API)

Für den Versand von Einzel-SMS in eigenen Anwendungen, entwickelt z.B. in Borland Delphi, PHP, C++, Java usw., ist ein einfacher HTTP-Aufruf notwendig. Es ist ebenfalls möglich über die Mail2SMS-Schnittstelle Einzel-SMS per E-Mail zu versenden.

 

Guthaben und aktuelles SMS-Paket abfragen

Mit Hilfe des Scripts sendsms.php kann ebenfalls das eigene Guthaben abgefragt werden. Infos dazu finden Sie am Ende dieser Seite.

 

Verwendung von Sonderzeichen

Beachten Sie bitte folgende Regeln zur Verwendung von Sonderzeichen:

 

Der HTTP-Aufruf

https://www.smsout.de/client/sendsms.php?APIkey=<API-Key aus dem SMSout.de Kundenbereich>&SMSTo=<rufnummer oder mehrere rufnummern mit semikolon(;) getrennt>&SMSType=<smstype>&SMSText=<smstext 160 Zeichen urlencoded>

Alternativer Aufruf mit Benutzername und Passwort, diese Variante sollte nicht mehr verwendet werden:

https://www.smsout.de/client/sendsms.php?Username=<smsout-username>&Password=<smsout-password>&SMSTo=<rufnummer oder mehrere rufnummern mit semikolon(;) getrennt>&SMSType=<smstype>&SMSText=<smstext 160 Zeichen urlencoded>

Ein Aufruf per http:// ist ebenfalls möglich, falls https:// durch Ihre Anwendung nicht unterstützt wird.

 

Die Parameter des HTTP-Aufrufs

<API-Key aus dem SMSout.de Kundenbereich> Im SMSout.de Kundenbereich finden Sie unter "Start" den API-Key.
<smsout-username> Geben Sie den SMSout-Benutzernamen an.

Hinweis: Verwenden Sie den Aufruf mit API-Key, um nicht den Nutzernamen/Passwort in der URL sichtbar zu übermitteln.

 
<smsout-password> Geben Sie das SMSout-Passwort an.

Hinweise:
Verwenden Sie den Aufruf mit API-Key, um nicht den Nutzernamen/Passwort in der URL sichtbar zu übermitteln.
Sollte das Passwort Sonderzeichen enthalten, dann müssen diese urlencoded übergeben werden.

 
<rufnummer oder mehrere rufnummern mit semikolon(;) getrennt> Geben Sie die Mobilfunknummer in der Form 0049<handyvorwahl><rufnummer> oder <handyvorwahl><rufnummer> an, nicht in der Form +49 oder 0049. Z.B. 00491791234567 oder 01791234567

Mehrere Rufnummern
Mehrere Rufnummern können mit Semikolon (;) getrennt angegeben werden. Alle angegebenen Rufnummern erhalten den gleichen SMS-Text.

Hinweis: Eine URL sollte nicht mehr als 255 Zeichen umfassen, daher sollte der Aufruf immer per HTTP Post erfolgen, ansonsten könnte Angaben nicht korrekt übermittelt werden..

Bei Angabe mehrerer Rufnummern fallen entsprechend die Kosten pro SMS für jede angegebene Rufnummer an.

 
<smstype>

 

 Folgende SMS-Typen können genutzt werden:

V1 um eine SMS ohne eigenem Absender zu versenden.

V2 NICHT mehr unterstützt, es wird automatisch V3 verwendet.

V3 um eine SMS mit eigenem Absender oder Absender-Text zu versenden.

V4 NICHT mehr unterstützt, es wird automatisch V1 verwendet.

V5 um eine SMS ohne eigenem Absender mit Versandstatusbericht zu versenden.

V6 um eine "Maxi"-SMS mit bis zu 1560 Zeichen zu versenden, der Versand muss wegen der Länge des Texts per HTTP POST erfolgen.

V7 für eine Text2Speech SMS, der Empfänger wird angerufen und der Text vorgelesen. Der Versand muss wegen der Länge des Texts per HTTP POST erfolgen.

 
<smstext urlencoded> Der Text der SMS muss urlencoded angegeben werden, siehe PHP Funktion urlencode().

Bei den SMS-Typen V1 bis V5 darf der SMS-Text die Länge von 160 Zeichen nicht überschreiten. Beim Typ V6 sind bis 1560 Zeichen zulässig, beim Typ V7 bis zu 1000 Zeichen. Der Versand der SMS mit mehr als 160 Zeichen MUSS per HTTP POST erfolgen. Mit Anzahl Zeichen ist immer der reine Text gemeint, nicht der urlencodede Text.

Alle SMS-Texte müssen mit der Zeichencodierung iso-8859-1 übergeben werden, verwenden Sie keine Unicode/UTF-8-Codierung für den SMS-Text.

 
Optionaler Parameter
&SendDateTime=<senddatetime> Fügen Sie den optionalen Parameter &SendDateTime=<senddatetime> hinzu um die SMS zu einem bestimmten Zeitpunkt zu versenden. Das Datum und Uhrzeit muss im Format JJJJ-MM-TT HH:NN:SS übergeben werden.

JJJJ=Jahr 4stellig
MM=Monat 2stellig
TT=Tag 2stellig
HH=Stunde 2stellig
NN=Minute 2stellig
SS=Sekunde 2stellig

 
&AltDisplayText= Nur bei den SMS-Typen V3 und V6 (SMS mit eigenem Absender oder Absender-Text, bzw. Maxi-SMS).

Sie können einen 11stelligen Text angeben, der als Absender verwendet werden soll. Der Text darf nur die Buchstaben A-Z, die Ziffern 0-9 und den Punkt (.) enthalten. Alternativ kann eine 14stellige Nummer übergeben werden, dieser Wert muss rein numerisch sein, vor den numerischen Wert wird im Normalfall die Landesvorwahl gesetzt, z.B. 49.

Wird die Angabe AltDisplayText= weggelassen, dann wird entweder die im SMSout-Kundenbereich hinterlegte Mobilfunknummer oder der hinterlegte 11stellige Text verwendet.

Hinweise:

  • Es dürfen keine Notrufnummern z.B. 112, 110 oder Worte, wie Polizei, System..., als Absender verwendet werden.
  • Für Österreich Provider A1: Nur Text als Absender verwenden, numerische Angaben werden als Spam geblockt.

 
&SMSCampaignName= Optional kann der Name einer SMS-Kampagne, url-encoded, angegeben werden. Im SMSout-Kundenbereich können Sie in der Statistik eine Aufstellung der versendeten SMS und angefallene Kosten für jede SMS-Kampagne abrufen.

Der Name der SMS-Kampagne sollte keine Umlaute/Sonderzeichen enthalten, werden Umlaute/Sonderzeichen angegeben, dann müssen diese iso-8859-1 codiert übergeben werden.

 

 

Rückgabe-Werte

 

Fehler bei Angabe einer Rufnummer:

Prüfen Sie einfach ob in der zurückgegebenen Zeichenkette das Wort "ERROR" vorkommt, in diesem Fall wurde die SMS nicht versendet. Im Falle eines fehlerhaften Versands kann der zusätzliche Wert hinter dem Wort ErrorText: ausgewertet werden, dieser gibt den aufgetretenen Fehler an. z.B.

Return: ERROR
ErrorCode: 9999
ErrorText: Login fehlgeschlagen


Fehler bei Angabe mehrerer Rufnummern:

 

Prüfen Sie einfach ob in der zurückgegebenen Zeichenkette das Wort "ERROR" vorkommt, in diesem Fall wurden eine oder mehrere SMS nicht versendet. Im Falle eines fehlerhaften Versands kann der zusätzliche Wert hinter dem Wort ErrorText: ausgewertet werden, dieser gibt den aufgetretenen Fehler an. z.B.

Return: ERROR
ErrorCode: 9985
ErrorText: SMS-Text fehlt.
SMSSentCount: Anzahl der erfolgreich versendeten SMS bevor der Fehler auftrat
Nur während des eigentlichen Sendeversuchs:
LastTriedCellNo: Mobilfunknummer, bei welcher der Fehler auftrat, an diese Mobilfunknummer und die weiteren Nummern wurde keine SMS gesendet.

 

 

Wurde eine SMS versendet, wird OK zurückgegeben. Zusätzlich werden die Kosten der SMS zurückgegeben, z.B.

Return: OK
ErrorCode: 0
CustomerId: Kundennummer
SMSCosts: Kosten der SMS brutto (mit MwSt.),
SMSCostsWithOutVAT: Kosten der SMS netto (ohne MwSt.),
SMSSentCount: Anzahl der versendeten SMS, nur bei Angabe mehrerer Rufnummern
SentItemsId*: interne ID der versendeten SMS, nur bei Einzel-SMS mit Antwort-Option verwendbar
SessionId: diese Angabe ist leer

* Mit Hilfe der SentItemsId kann eine spätere Antwort auf die SMS zugeordnet werden, dazu muss im Kundenbereich unter "Pers.Daten" ein eigenes Script beim Eingang einer SMS und/oder Statusberichts angegeben werden.

 

Beispiel-URLs

Versand einer SMS ohne Absender an die Mobilfunknummer 01791234567 und SMS-Text Das ist eine Test SMS.

https://www.smsout.de/client/sendsms.php?APIkey=smsout-api-key-aus-kundenbereich&SMSTo=01791234567&SMSType=V1&SMSText=Das+ist+eine+Test+SMS

 

Versand mehrerer SMS ohne Absender an die Mobilfunknummern 01791234567 und 01791234568 mit dem SMS-Text Das ist eine Test SMS.

https://www.smsout.de/client/sendsms.php?APIkey=smsout-api-key-aus-kundenbereich&SMSTo=01791234567;01791234568&SMSType=V1&SMSText=Das+ist+eine+Test+SMS

 

Beispiel Versand einer SMS mit eigenem Absender an die Mobilfunknummer 01791234567 und SMS-Text Das ist eine Test SMS.

https://www.smsout.de/client/sendsms.php?APIkey=smsout-api-key-aus-kundenbereich&SMSTo=01791234567&SMSType=V3&SMSText=Das+ist+eine+Test+SMS

 

Beispiel Versand einer SMS mit eigenem Absender aber mit dem Absender-Text SMSout_SMS and die Mobilfunknummer 01791234567 und SMS-Text Das ist eine Test SMS.

https://www.smsout.de/client/sendsms.php?APIkey=smsout-api-key-aus-kundenbereich&SMSTo=01791234567&SMSType=V3&AltDisplayText=SMSout_SMS&SMSText=Das+ist+eine+Test+SMS

 

 

Einfaches Beispiel in Delphi 7 mit den Indy-Internet-Komponenten (Indy Komponenten)

// Funktion für URLEncode

// in neuere Delphi-Versionen ist ebenfalls möglich:
// uses System.NetEncoding, System.SysUtils; urlencoded := TNetEncoding.Url.Encode(<wert>, [], [], System.SysUtils.TEncoding.ANSI);
function UrlEncode(Src : String) : String;
var
I : Integer;
begin
Result := '';
For I := 1 to Length(Src) Do
begin
If Src[I] = '+' then
 Result := Result + '%' + IntToHex(ord(Src[I]), 2)
else
If Src[I] = ' ' then
 Result := Result + '+'
else
If Src[I] in ['a'..'z', 'A'..'Z', '0'..'9'] Then
 Result := Result + Src[I]
else
If (Ord(Src[I]) < 32) or (Ord(Src[I]) >= 127) Or (Src[I] in [':', '/', '\', '<', '>', '?', ';', '=', '&']) Then
 Result := Result + '%' + IntToHex(ord(Src[I]), 2)
else
 Result := Result + Src [I]
end;
end;

// SMSTyp darf nur 1, 2, 3, 4, 5, 6, 7 sein.
// SMSText maximal 160 Zeichen
// Indy HTTP Komponente wird für den SMS-Versand genutzt

// Für SMSTyp 6 und 7 muss der Aufruf mit HTTP.Post() ausgeführt werden

function SendSMS(const SMSoutAPIkey, SMSoutUsername, SMSoutPassword: String; const SMSTo: String; const SMSTyp: Integer; const SMSText: String): String;
Var
HTTP : TIdHTTP;
IdSSLIOHandler: TIdSSLIOHandlerSocketOpenSSL;
Data : String;


begin

   HTTP := TIdHTTP.Create(NIL);
  IdSSLIOHandler:= TIdSSLIOHandlerSocketOpenSSL.Create; // for SSL connections
  HTTP.IOHandler := IdSSLIOHandler;
   try

   // mit API key
   Data := Format('?APIkey=%s&SMSTo=%s&SMSType=V%d&SMSText=%s', [SMSoutAPIkey,
                              SMSTo, SMSTyp, UrlEncode(SMSText)] );

    { Alternative mit Benutzername und Passwort

     Data := Format('?Username=%s&Password=%s&SMSTo=%s&SMSType=V%d&SMSText=%s', [SMSoutUsername,
                             UrlEncode(SMSoutPassword), SMSTo, SMSTyp, UrlEncode(SMSText)] );
   }

    Result := HTTP.Get('https://www.smsout.de/client/sendsms.php' +  Data)
  finally

    HTTP.Free;
  end;
end;

// Testen

var
 S: String;

S := SendSMS('apikey aus smsout.de kundenbereich', 'username', 'password', '01791234567', 1, 'Das ist eine Test-SMS');

If Pos('ERROR', S) > 0 Then
  ShowMessage('SMS-Versand fehlgeschlagen, Fehler: ' + S)
else
  ShowMessage('Die SMS wurde versendet, Rückgabe: ' + S);

Beispiel in PHP 4/5/7

<?php

# Zugangsdaten
$APIkey = "apikey as smsout.de Kundenbereich";
$Username = "smsout-username";
$Password = urlencode("smsout-passwort");

# Zielrufnummer korrekt angeben!
$SMSTo = "01791234";

# Text der SMS, maximal 160 Zeichen
# beim Typ V6 bis zu 1560 Zeichen, wobei der Aufruf beim Typ 6 per HTTP Post erfolgen muss
# beim Typ V7 bis zu 1000 Zeichen, wobei der Aufruf beim Typ 7 per HTTP Post erfolgen muss
$SMSText = urlencode("Das ist eine Test SMS");

# SMS ohne eigenem Absender versenden, andere Werte V2, V3, V4, V5, V6 oder V7
$SMSType = "V1";

# Aufruf für den Versand der SMS
# Rückgabe ein Array mit dem Versandstatus

$result = file("https://www.smsout.de/client/sendsms.php?APIkey=$APIkey&SMSTo=$SMSTo&SMSType=$SMSType&SMSText=$SMSText");

/* Alternativ mit Übergabe Benutzername und Passwort
$result = file("https://www.smsout.de/client/sendsms.php?Username=$Username&Password=$Password&SMSTo=$SMSTo&SMSType=$SMSType&SMSText=$SMSText");
*/

if(is_array($result)) # falls es kein array ist, dann einfach so ausgeben
print join("<br>", $result);
else
print $result;

?>

 

Guthaben und aktuelles SMS-Paket abfragen

Mit dem Aufruf

https://www.smsout.de/client/sendsms.php?APIkey=<smsout-api-key-aus-kundenbereich>&GetAccountData

oder

https://www.smsout.de/client/sendsms.php?Username=<smsout-username>&Password=<smsout-password>&GetAccountData

kann das Guthaben und das aktuelle SMS-Paket abgefragt werden.

Als Rückgabewert bei korrekter Angabe von API Key oder Benutzername/Passwort erhalten Sie diese Daten:

Return: OK
ErrorCode: 0
CustomerId: Kundennummer
AvailMoney: Verfügbares Guthaben mit MwSt.
AvailMoneyWithOutVAT: Verfügbares Guthaben ohne MwSt.
SMSPackageName: Aktuelles SMS-Paket
SessionId:

 

SMS mit UTF-8 codierten Zeichen

Anstatt des Scripts sendsms.php verwenden Sie das Script sendsmsutf8.php. Dieses Script wandelt alle UTF-8 codierten Zeichen vor dem SMS-Versand in iso-8859-1 codierte Zeichen um. Sind Zeichen nicht in iso-8859-1 umwandelbar, dann werden ? im SMS-Text enthalten sein.
Verwenden Sie das spezielle Script sendsmsutf8.php nur, wenn eine Umwandlung in iso-8859-1 nicht oder nur schwer möglich ist z.B. in JavaScript auf utf-8 codierten Webseiten oder in Smartphone Apps (SMSout App für Android).

 

SMSout und LinOTP

Als SMS Provider Konfiguration für LinOTP müssen diese Daten hinterlegt werden:

{"URL":"https://www.smsout.de/client/sendsmsutf8.php",
"PARAMETER": {
     "APIkey":"<api key aus SMSout.de Kundenbereich>",
     "SMSType":"V3"
  },
"SMS_TEXT_KEY":"SMSText",
"SMS_PHONENUMBER_KEY":"SMSTo",
"HTTP_Method":"GET",
"RETURN_SUCCESS":"Return: OK"
}

Alternativ mit Übergabe von Benutzername und Passwort (nicht empfohlen):

{"URL":"https://www.smsout.de/client/sendsmsutf8.php",
"PARAMETER": {
     "Username":"<smsout-username>",
     "Password":"<smsout-password>",
     "SMSType":"V3"
  },
"SMS_TEXT_KEY":"SMSText",
"SMS_PHONENUMBER_KEY":"SMSTo",
"HTTP_Method":"GET",
"RETURN_SUCCESS":"Return: OK"
}

Für <api key aus SMSout.de Kundenbereich> muss der API Key aus dem SMSout.de Kundenbereich hinterlegt werden. Beim Aufruf mit Benutzername und Passwort muss für <smsout-username> der SMSout.de-Nutzername und für <smsout-password> das SMSout.de-Passwort hinterlegt werden.
Die SMS wird mit Absender versendet (V3), dazu wird die Absender-Nummer oder hinterlegte Absender-Text aus dem SMSout.de-Kundenbereich verwendet.

 

Siehe auch

Mail2SMS-Schnittstelle

 

<< Zurück zu SMSout.de