Deutsch

SMS Programmierschnittstelle (SMS API)

Falls du es noch nicht getan hast, werfe bitte zuerst einen Blick auf die Ersten Schritte bevor du dich hier zu sehr vertiefts. Danke!

SMS Senden API

Funktion: sendSms

Versendet GSM und Unicode SMS Text Nachrichten. Fasst lange Nachrichten automatisch zu langen SMS (mit bis zu 765 Zeichen) zusammen.
Gibt ein JSON Objekt mit einer Bestätigung oder Fehlermeldung zurück.

POST/GET Beispiel

username=xxx&password=yyyy&function=sendSms &number=+491234567890&message=Have%20a%20nice%20day! &senderid=+44987654321&callbackurl=http://www.my-server.com/callback.php

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"sendSms",
    "number":"+491234567890",
    "message":"Have a nice day!",
    "senderid":"+449876543210",
    "callbackurl":"http://www.my-server.com/callback.php"
}

Erforderliche Parameter

Parameter Beschreibung Typ
number Die Rufnummer im internationalen Format. Zum Beispiel: +49123456789, 49123456789 oder 0049123456789 string
message The SMS Inhalt. My-Cool-SMS erkennt automatisch ob es sich um eine Unicode oder GSM Nachricht handelt und versendet die SMS im jeweiligen Format.
Der Uniocde Parameter kann benutzt werden um eine bestimmte Kodierung zu erzwingen. Falls Unicode auf true gesetzt wird muss der SMS Inhalt in UCS2 Notation übergeben werden. Wenn Unicode auf false gesetzt ist, wird die Nachricht im GSM Standard versendet und darf nur Zeichen aus dem GSM7 Alphabet enthalten.
Lange Nachrichten werden automatisch konkateniert (bis zu fünf Nachrichten oder 765 Zeichen für GSM bzw. 335 Zeichen für Unicode SMS).
Bitte beachte dass der Unicode Paramater bei Aufrufen mit der GET Methode *immer* verwendet werden sollte, da es in diesem Fall nicht möglich ist automatisch zwischen Unicode und GSM zu unterscheiden.
string
Hinweis: Erfahre mehr über GSM, Unicode und UCS2.

Optionale Parameter

Parameter Beschreibung Typ
unicode Erzwingt eine Unicode oder GSM Kodierung der SMS. Falls true verwendet wird muss der SMS Inhalt mit UCS2 Notation übergeben werden. Falls auf false gesetzt darf der SMS Inhalt lediglichen Zeichen aus dem GSM7 Alphabet enthalten.
Ist auf NULL voreingestellt und erkennt in diesem Fall die zu verwendende Kodierung automatisch.
boolean
senderid Rufnummer im internationalen Format. Zum Beispiel: +49123456789, 49123456789 oder 0049123456789 Alternativ darf eine alphanumerische Zeichenkette mit bis zu 11 Zeichen verwendet werden, z.B. "Firmenname" string
scheduletime Versendet die Nachricht zu einem bestimmten Zeitpunkt. Erfordert einen Timestamp im ATOM Format (mit Zeitzone), zum Beispiel: "2011-04-17T17:59:36.67+08" oder "2011-04-17 17:59:36-02" timestamp with timezone
callbackurl Rückruf URL für Status-Updates und Sendeberichte für diese Nachricht. Zum Beispiel: http://www.mein-server.de/callback.php string
Hinweis: Erfahre mehr über Sendebericht Rückrufe.

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "body":"Have a nice day!",
    "bodyucs2":"0048006100760065002000610020006E00690063006500200064",
    "bodygsm7":"486176652061206E6963652064617921",
    "number":"+491234567890"
    "senderid":"+449876543210",
    "senderidenabled":true,
    "unicode":false,
    "numchars":321,
    "escapenumchars":0,
    "smscount":3,
    "charge":0.112,
    "balance":752.121,
    "countrycode":"DE",
    "prefix":"+49",
    "timestamp":"2013-04-02T22:27:22-07:00",
    "callbackurl":"http://www.my-server.com/callback.php"
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
smsid Unique ID für diese SMS. Sollte auf Client-Seite als Referenz ID für Sendeberichte gespeichert werden. string(32)
body Der SMS-Inhalt als Unicode Text-String string
bodyucs2 Der SMS-Inhalt in UCS2 Bytecode-Notation string
bodygsm7 Der SMS-Inhalt in GSM7 Bytecode-Notation (oder NULL falls die Nachricht als Unicode versendet wurde) string || NULL
senderid Indicates the sender id used for the sent message. string
senderidenabled Zeigt an ob die Ziel-Rufnummer dynamische Senderkennungen unterstützt boolean
unicode Zeigt an ob die Nachricht als Unicode oder GSM verschickt wurde boolean
numchars Zeigt an wieviele Zeichen für die SMS verwendet wurden integer
escapenumchars Zeigt an wieviele Zeichen escaped werden mussten (und als zwei Zeichen im GSM Format zählten) integer
smscount Zeigt an ob die Nachricht zu einer langen SMS zusammengefasst wurde und aus wievielen SMS-Längen sie besteht integer
charge Zeigt an wieviel für diese SMS berechnet wurde float
balance Zeigt das Rest-Guthaben im verwendeten Konto an float
countrycode Indicates to which country the SMS was sent to (ISO Code) string
prefix Indicates the prefix of the country to which the SMS was sent to string
timestamp Timestamp of when the SMS was accepted (using the time zone you were on when you logged in to the web portal the last time or UTC if unknown). Given in DATE_ATOM Format (e.g. 2013-04-02T22:27:22-07:00). string
callbackurl Rückruf-URL an welche Status-Aktualisierungen und Sendeberichte für diese Nachricht gesendet werden. string || NULL

Funktionsspezifische API Fehler

Fehlercode Fehlerbeschreibung
210 Die Rufnummer scheint ungültig zu sein
211 Der message Parameter enthält keinen Text
212 Der message Parameter ist zu lang
213 Der unicode Parameter ist true aber der message parameter wurde nicht in UCS2-Notation übergeben
214 Der unicode Parameter ist false aber die Nachricht wurde in UCS2-Notation übergeben
215 Der unicode Parameter ist false aber die Nachricht enthält Zeichen ausserhalb des GSM7 Alphabets
216 The input for Sender ID is invalid. You may use a phone number or an alphanumeric text with up to eleven characters (A-Z, a-z, 0-9 and the dash symbol).
217 Kurzcode Senderkennungen sind nicht erlaubt
218 Die Rückruf-URL scheint ungültig zu sein
219 Die übergebene Sendezeit scheint ungültig zu sein. Erforderliches Format ist ATOM mit Zeitzone, zum Beispiel: "2011-04-17T17:59:36.67+08" oder "2011-04-17 17:59:36-02"
Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

SMS Empfangen API

Rückruf: pushIncomingSms

Falls in dein Posteingangs-Einstellungen eine Rückruf URL angegeben wurde leitet My-Cool-SMS die Nachricht automatisch auf die angegebene URL weiter. Die Rückruf-URL kann mittels Web-Interface in den Posteingangs-Einstellungen gesetzt werden.

Rückruf-Beispiel

POST /your/callbackurl.php HTTP/1.1
Content-Type: application/json
Host: www.your-server.com
User-Agent: My-Cool-SMS Incoming SMS Callback
Content-Length: n
Cache-Control: no-cache
Connection: close

{
   "from":"+1230987654321",
   "fromcountrycode":"US",
   "to":"+440987654321",
   "unicode":false,
   "smscount":1,
   "body":"Have a nice day with incoming SMS!",
   "bodyucs2":"0048006100760065002000610020006e00690063006500200064",
   "bodygsm7":"5374616666206D6565746925",
   "numchars":54,
   "escapenumchars":0,
   "cost":"0.010"
}
Hinweis: Erfahre hier wie JSON Rückrufe am besten verarbeitet werden können.

Rückruf-Parameter

Schlüssel Beschreibung Typ
from Die Senderkennung mit der die SMS verschickt wurde. Kann eine Rufnummer im internationale Format oder eine alphanumerische Zeichenkette mit bis zu elf Zeichen enthalten. string
fromcountrycode Enthält das ISO-Format Länderkürzel (zwei Buchstaben) der Senderkennung. Falls die Senderkennung alphanumerisch ist wird hier NULL zurückgegeben. string(2) || NULL
to Die Rufnummer an welche die SMS geschickt wurde (deine My-Cool-SMS Online Rufnummer). string
unicode Zeigt an ob die Nachricht in Unicode oder GSM gesendet wurde. boolean
smscount Zeigt an ob die Nachricht zu einer langen SMS zusammengefasst wurde und aus wievielen SMS-Längen sie besteht integer
body Der SMS-Inhalt als Unicode Text-String string
bodyucs2 Der SMS-Inhalt in UCS2 Bytecode-Notation string
bodygsm7 Der SMS-Inhalt in GSM7 Bytecode-Notation (oder NULL falls die Nachricht als Unicode versendet wurde) string
numchars Zeigt an wieviele Zeichen für die SMS verwendet wurden integer
escapenumchars Zeigt an wieviele Zeichen escaped werden mussten (und als zwei Zeichen im GSM Format zählten) integer
cost Zeigt an wieviel für diese SMS berechnet wurde float

Funktion: getIncomingSms

Queries the server for received SMS text messages. Returns a status summary for the selected virtual number and an array containing inbound SMS. Can be customized by using the optional parameters.

POST/GET Beispiel

username=xxx&password=yyy&function=getIncomingSms&virtualnumber=+449876543201

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"getIncomingSms",
    "virtualnumber":"+449876543201"
}

Erforderliche Parameter

Parameter Beschreibung Typ

Optionale Parameter

Parameter Beschreibung Typ
thresholdid Only messages with a higher id should be returned. This parameter is required to only receive messages that have been received after the ones that were fetched already. Every message fetched with the getIncomingSms function contains a unique id, which should be stored on client side in order to use it here. Defaults to 0. integer
limit The maximum amount of messages to be returned. Defaults to 25. If set to 0, no limit will be applied. integer
order Specifies the order in which the results should be returned. Can be "ASC" or "DESC". Defaults to "DESC" string
thresholdoperator Specifies whether the returned messages should have higher or lower ids as compared to the id provided in thresholdid. Can be either "gt" (greater than) or "lt" (lower than). Defaults to "gt" string(2)
virtualnumber The virtual number for which sms text messages should be fetched. If no virtual number is provided inbound texts for all virtual numbers will be returned. string
unreadsmstosyncids This parameter is useful if you want to sync the read/unread status of your inbound SMS pipe on several devices. Provide the ids of the messages that are marked as unread on your device to receive a list of ids of messages that have been marked as read on a different device. You can use those ids to update the read/unread status on your device. If no messages were marked as read the list will be empty. array[int]

Antwort bei einem erfolgreichen Aufruf

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "minid":177,
   "messages":[
      {
         "id":201,
         "virtualnumber":"+449876543201",
         "senderid":"+886983029751",
         "body":"Have a nice day!",
         "bodyucs2":"AAAA",
         "bodygsm7":"AA",
         "unicode":false,
         "timestamp":"2011-08-10 00:08:37.488+08",
         "unixtimestamp":"1316531343.9",
         "numchars":16,
         "escapechars":0,
         "smscount":1,
         "charge":"0.015",
         "senderidcountrycode":"TW",
         "virtualnumbercountrycode":"HK"
      }
   ]
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
total The total number of messages on this virtual number integer
fetched The number of messages that were fetched integer
maxid The "maxid" parameter indicates the highest unique id (last message) on this virtual number. This value should be stored and use for future queries as "thresholdid" parameter in order to just fetch new messages. integer
minid The lowest sms id found for this user. Can be used for client side reference. integer
messages Contains an array of SMS text objects (with self-explaining attribute names, see example). array

Funktionsspezifische API Fehler

Fehlercode Fehlerbeschreibung
232 Die Rufnummer scheint ungültig zu sein
233 The virtual number is either invalid or not registered with this user account. Please contact service@my-cool-sms.com for assistance.
234 The provided thresholdid is invalid
235 Ungültiger limit Parameter
236 Invalid order parameter
242 No virtual numbers found.
Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Guthaben-Info API

Funktion: getBalance

Gibt ein JSON Objekt mit dem Restguthaben (oder eine Fehlermeldung) zurück

POST/GET Beispiel

username=xxx&password=yyyy&function=getBalance

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"getBalance"
}

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "balance":752.210
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
balance Verbleibendes Rest-Guthaben in Euro float

Sendebericht API

Sendebericht können in My-Cool-SMS auf zwei Art und Weisen empfangen werden. Zum einen kann der My-Cool-SMS Server mit getDeliveryReport gepollt werden und zum anderen können HTTP Rückrufe in Echtzeit via pushDeliveryReport empfangen werden. Bitte beachte dabei dass Sendeberichte für Mailings nur mit getDeliveryReport verfügbar sind.

Funktion: getDeliveryReport

Gibt einen Sendebericht für eine einzelne SMS (die mit sendSms verschickt wurde) oder einen Sendebericht für ein Mailing zurück. Falls ein Mailing-Listen Sendebericht angefordert wird muss der optionale groupkey Parameter auf true gesetzt werden. Das zurückgegebene JSON-Objekt kann in diesem Fall eine kompakte Zusammenfassung enthalten oder einen detaillierten Bericht für jeden einzelnen Abonennten (indem der optionale Parameter mailingdetails auf true gesetzt wird).

POST/GET Beispiel

username=xxx&password=yyyy&function=getDeliveryReport &id=ce184cc0a6d1714d1ac763f4fe89f521

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReport",
    "id":"ce184cc0a6d1714d1ac763f4fe89f521"
}

Erforderliche Parameter

Parameter Beschreibung Typ
id Referenz-ID. Entweder eine SMS ID (wie von sendSms zurückgegeben) oder ein Mailing-Gruppenschlüssel (wie von sendMailing zurückgegeben).
Falls ein Mailing-Gruppenschlüssel verwendet wird muss der optionale Parameter groupkey auf true gesetzt werden.
string

Optionale Parameter

Parameter Beschreibung Typ
groupkey Muss auf true gesetzt werden falls ein Gruppenschlüssel als id Parameter verwendet wird (und ein Sendebericht für ein Mailing zurückgegeben werden soll). Ist auf false voreingestellt. string
mailingdetails Muss auf true gesetzt werden falls, zusätzlich zur kompakten Zusammenfassung, ein detaillierter Sendebericht für jeden einzelnen Abonennten zurückgegeben werden soll. Ist auf false voreingestellt. string

Antwort bei einem erfolgreichen Aufruf: groupkey=false (Voreinstellung)

{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "status":"SMS_STATUS_DELIVERED"
}

Rückgabewerte bei einem erfolgreichen Aufruf: groupkey=false (Voreinstellung)

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
smsid Die Referenz-ID für diesen Sendebericht string
status Zeigt den Status dieser SMS an string
Hinweis: Erfahre mehr über mögliche Status-Codes.

Antwort bei einem erfolgreichen Aufruf: groupkey=true

{
    "success":true,
    "groupkey":"d3743cc0a6d1714d1ac763f4fe89f521",
    "total":12,
    "SMS_STATUS_QUEUED":0,
    "SMS_STATUS_AT_CARRIER":0,
    "SMS_STATUS_DELIVERED":12,
    "SMS_STATUS_BOUNCED":0,
    "SMS_STATUS_ERROR":0
}
Hinweis: Erfahre mehr über mögliche Status-Codes.

Antwort bei einem erfolgreichen Aufruf: groupkey=true&mailingdetails=true

{
    "success":true,
    "groupkey":"d3743cc0a6d1714d1ac763f4fe89f521",
    "total":12,
    "SMS_STATUS_QUEUED":0,
    "SMS_STATUS_AT_CARRIER":0,
    "SMS_STATUS_DELIVERED":12,
    "SMS_STATUS_BOUNCED":0,
    "SMS_STATUS_ERROR":0,
    "details":[
        {
            "recipient":"+1230987654321",
            "status":"SMS_STATUS_DELIVERED"
        },
        {
            "recipient":"+1230987654322",
            "status":"SMS_STATUS_DELIVERED"
        }, 
        (...)
    ]
}
Hinweis: Erfahre mehr über mögliche Status-Codes.

Funktionsspezifische API Fehler

Fehlercode Fehlerbeschreibung
223 Unbekannte SMS ID
224 Unbekannter Gruppenschlüssel
Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Funktion: getDeliveryReports

Returns delivery reports for a list of messages.

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReports",
    "ids":[
        "ce184cc0a6d1714d1ac763f4fe89f521",
        "d1ac763f4fe89f521ce184cc0a6d1714"
    ]
}

Erforderliche Parameter

Parameter Beschreibung Typ
ids An array of sms ids to perform the delivery status lookup for. array[]

Antwort bei einem erfolgreichen Aufruf:

{
    "success":true,
    "reports": [
        {
            "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
            "status":"SMS_STATUS_DELIVERED"
        },
        {
            "smsid":"d1ac763f4fe89f521ce184cc0a6d1714",
            "status":"SMS_STATUS_DELIVERED"
        }
    ]
}

Rückgabewerte bei einem erfolgreichen Aufruf:

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
reports[] Contains an array with delivery report objects. Each object contains the reference id (smsid) and the corresponding delivery status (status). array
reports[n].smsid Contains the reference sms id for this delivery report string
reports[n].status Contains the delivery status for this SMS. Possible states are: SMS_STATUS_QUEUED, SMS_STATUS_AT_CARRIER, SMS_STATUS_DELIVERY_DELAYED, SMS_STATUS_DELIVERED, SMS_STATUS_BOUNCED, SMS_STATUS_EXPIRED, SMS_STATUS_ERROR or UNKNOWN_ID. string
Hinweis: Erfahre mehr über mögliche Status-Codes.

Funktionsspezifische API Fehler

Fehlercode Fehlerbeschreibung
240 The input for the "ids" parameter seems invalid. Please make sure to provide an array with valid sms ids.
241 The maximum number of delivery reports per request is 100.
Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Funktion: getRecentReports

Gibt ein JSON-Objekt mit Sendeberichten für die am neulichsten versendeten SMS zurück.

POST/GET Beispiel

username=xxx&password=yyyy&function=getRecentReports&limit=10

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"getRecentReports",
    "limit":10
}

Erforderliche Parameter

Parameter Beschreibung Typ
limit Gibt an wieviele Sendeberichte zurückgegeben werden sollen. integer

Antwort bei einem erfolgreichen Aufruf

{
   "success":true,
   "reports":[
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day!",
         "bodyucs2":"0048006100760065002000610020006E006900630065002",
         "bodygsm7":"486176652061206E6963652064617921",
         "unicode":false,
         "timesent":"2011-04-19 12:08:37.233+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day!",
         "bodyucs2":"0048006100760065002000610020006E006900630065002",
         "bodygsm7":"486176652061206E6963652064617921",
         "unicode":false,
         "timesent":"2011-04-19 12:01:03.338+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day with long Unicode messages! \u7e41",
         "bodyucs2":"0048006100760065002000610020006e00690063006500",
         "bodygsm7":"",
         "unicode":true,
         "timesent":"2011-04-18 21:53:24.787+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      (...)
   ]
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
number Ziel-Rufnummer string
senderid Die Senderkennung mit der die Nachricht versendet wurde. string
body Der SMS-Inhalt als Unicode Text-String string
bodyucs2 Der SMS-Inhalt in UCS2 Bytecode-Notation string
bodygsm7 Der SMS-Inhalt in GSM7 Bytecode-Notation (oder NULL falls die Nachricht als Unicode versendet wurde) string
unicode Zeigt an ob die Nachricht als Unicode oder GSM verschickt wurde boolean
timesent Der Zeitpunkt zu dem die Nachricht versendet wurde. timestamp with time zone
status Zeigt den Status dieser SMS an string
Hinweis: Erfahre mehr über mögliche Status-Codes.

Funktionsspezifische API Fehler

Fehlercode Fehlerbeschreibung
225 Ungültiger limit Parameter
Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Rückruf: pushDeliveryReport

Falls der callbackurl Parameter im Aufruf der sendSms-Funktion gesetzt wurde, gibt My-Cool-SMS automatisch (und in Echtzeit) einen Sendebericht an die angegebene URL zurück. Der Rückruf wird immer als JSON Objekt in der HTTP Raw-Data gesendet.

Rückruf-Beispiel

POST /your/callbackurl.php HTTP/1.1
Content-Type: application/json
Host: www.your-server.com
User-Agent: My-Cool-SMS Delivery Report
Content-Length: n
Cache-Control: no-cache
Connection: close

{
    "smsid":"498673a1f58df975ab95da33884d9e14",
    "status":"SMS_STATUS_DELIVERED"
}
Hinweis: Erfahre hier wie JSON Rückrufe am besten verarbeitet werden können.

Rückruf-Parameter

Schlüssel Beschreibung Typ
smsid Die Unique ID der SMS für welche der Rückruf bedeutsam ist. Der smsid Parameter wurde ursprünglich in der Antwort auf den sendSMS Funktionsaufruf zurückgegeben. string(32)
status Zeigt den Status dieser SMS an string

Status-Referenz

Status Beschreibung
SMS_STATUS_QUEUED In Warteschleife - Diese Nachricht ist in der Wartseschleife und wurde noch nicht verschickt.
SMS_STATUS_AT_CARRIER Beim Mobilfunkbetreiber - Die SMS wurde and den Mobilfunkbetreiber gesendet und sollte als 'Zugestellt' markiert werden sobald sie auf dem Mobiltelefon eingeht.
Bitte beachte dass manche Mobilfunkanbieter keinen Sendebericht zur Verfügung stellen. In diesem Fall wird die Nachricht als 'Beim Mobilfunkanbieter' angezeigt obwohl sie auf dem Mobiltelefon eingegangen ist.
SMS_STATUS_DELIVERY_DELAYED Zustellung verzögert - Die Zustellung der Nachricht verzögert sich.
SMS_STATUS_DELIVERED Zugestellt - Die Nachricht wurde erfolgreich zugestellt.
SMS_STATUS_BOUNCED Nicht zugestellt - Diese Nachricht konnte vom Mobilfunkbetreiber des Empfängers nicht zugestellt werden. Mögliche Gründe sind eine ungültige Nummer oder Sender ID, das Telefon sich ausserhalb des Mobilfunknetzes befindet oder Datenstaus beim Mobilfunkbetreiber.
SMS_STATUS_EXPIRED Abgelaufen - Die Zustellungs-Phase für diese Nachricht ist abgelaufen und die SMS konnte nicht zugestellt werden.
Dies geschieht normalerweise wenn das Ziel-Telefon abgelaufen ist oder sich zu lange ausser Netzwerk-Reichweite befindet.
SMS_STATUS_ERROR Fehlgeschlagen - Die Zustellung ist fehlgeschlagen (dein Konto wurde nicht belastet).
Mögliche Gründe sind eine uns unbekannte Vorwahl or temporäre Netzwerkprobleme. Bitte kontaktiere den My-Cool-SMS Support falls die verwendete Nummer mit Sicherheit korrekt ist.

Funktion: getOutboundSms

This function is useful if you want to sync the outbound SMS streams in your account for different devices. It queries the server for outbound sms data and returns and array delivery statuses and additional information on the messages, such as content and timestamps.

POST/GET Beispiel

username=xxx&password=yyy&function=getOutboundSms

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"getOutboundSms"
}

Erforderliche Parameter

Parameter Beschreibung Typ

Optionale Parameter

Parameter Beschreibung Typ
thresholdid Use this parameter to specify the particular message for which you would like to check if messages were sent before or after. Combine with the thresholdoperator parameter to specify if you need messages with lower or greater ids. string(32)
limit The maximum amount of messages to be returned. Defaults to 25. integer
thresholdoperator Specifies whether the returned messages should have higher or lower ids as compared to the id provided in thresholdid. Can be either "gt" (greater than) or "lt" (lower than). Defaults to "gt" string
order Specifies the order in which the results should be returned. Can be "ASC" or "DESC". Defaults to "DESC" string

Antwort bei einem erfolgreichen Aufruf

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "minid":177,
   "messages":[
      {
        "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
        "body":"Have a nice day!",
        "bodyucs2":"0048006100760065002000610020006E00690063006500200064",
        "bodygsm7":"486176652061206E6963652064617921",
        "number":"+491234567890"
        "senderid":"+449876543210",
        "senderidenabled":"+449876543210",
        "unicode":false,
        "numchars":321,
        "escapenumchars":0,
        "smscount":3,
        "charge":0.112,
        "countrycode":"DE",
        "prefix":"+49",
        "timestamp":"2013-04-02T22:27:22-07:00",
        "callbackurl":"http://www.my-server.com/callback.php",
        "status":"SMS_STATUS_DELIVERED"
      }
   ]
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
total The total number of SMS sent on this account. integer
fetched The total number of SMS returned by this query. integer
maxid Indicates the newest sms returned by this query. Can be used as new thresholdoperator parameter in a subsequent API call. integer
minid Indicates the oldest sms returned by this query. Can be used as new thresholdoperator parameter in a subsequent API call. integer
messages An array containing objects with the outbound SMS returned by this query. The SMS object attributes correspond to the return values of the sendSms function (please see that section for details). array

Funktionsspezifische API Fehler

Fehlercode Fehlerbeschreibung
234 The provided thresholdid is invalid
235 Ungültiger limit Parameter
236 Invalid order parameter
Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Mailing-Listen API

Funktion: sendMailing

Sendet eine SMS Text Nachricht an eine My-Cool-SMS Mailing-Liste. Mailing-Listen können über das Web Interface erstellt und verwaltet werden.
Gibt ein JSON Objekt mit einer Bestätigung oder Fehlermeldung zurück.

POST/GET Beispiel

username=xxx&password=yyyy&function=sendMailing &uniqueid=75F3FAB&message=Staff%20meeting%20in%2020%20minutes. &senderid=MyCompany

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"sendMailing",
    "uniqueid":"75F3FAB",
    "message":"Staff meeting in 20 minutes. Balcony meeting room.",
    "senderid":"MyCompany"
}

Erforderliche Parameter

Parameter Beschreibung Typ
uniqueid Die Unique ID der Mailing-Liste. Die Unique IDs für alle Mailing-Listen können im Web Interface unter "Verwalten" der jeweiligen Mailing-Liste eingesehen werden. string
message The SMS Inhalt. My-Cool-SMS erkennt automatisch ob es sich um eine Unicode oder GSM Nachricht handelt und versendet die SMS im jeweiligen Format.
Der Uniocde Parameter kann benutzt werden um eine bestimmte Kodierung zu erzwingen. Falls Unicode auf true gesetzt wird muss der SMS Inhalt in UCS2 Notation übergeben werden. Wenn Unicode auf false gesetzt ist, wird die Nachricht im GSM Standard versendet und darf nur Zeichen aus dem GSM7 Alphabet enthalten.
Lange Nachrichten werden automatisch konkateniert (bis zu fünf Nachrichten oder 765 Zeichen für GSM bzw. 335 Zeichen für Unicode SMS).
Bitte beachte dass der Unicode Paramater bei Aufrufen mit der GET Methode *immer* verwendet werden sollte, da es in diesem Fall nicht möglich ist automatisch zwischen Unicode und GSM zu unterscheiden.
string
Hinweis: Erfahre mehr über GSM, Unicode und UCS2.

Optionale Parameter

Parameter Beschreibung Typ
unicode Erzwingt eine Unicode oder GSM Kodierung der SMS. Falls true verwendet wird muss der SMS Inhalt mit UCS2 Notation übergeben werden. Falls auf false gesetzt darf der SMS Inhalt lediglichen Zeichen aus dem GSM7 Alphabet enthalten.
Ist auf NULL voreingestellt und erkennt in diesem Fall die zu verwendende Kodierung automatisch.
boolean
senderid Rufnummer im internationalen Format. Zum Beispiel: +49123456789, 49123456789 oder 0049123456789 Alternativ darf eine alphanumerische Zeichenkette mit bis zu 11 Zeichen verwendet werden, z.B. "Firmenname" string
scheduletime Versendet die Nachricht zu einem bestimmten Zeitpunkt. Erfordert einen Timestamp im ATOM Format (mit Zeitzone), zum Beispiel: "2011-04-17T17:59:36.67+08" oder "2011-04-17 17:59:36-02" timestamp with time zone
Hinweis: Erfahre mehr über Sendebericht Rückrufe.

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "groupkey":"041d3b026a50669481695dcf9e1985e4",
    "body":"Staff meeting in 20 minutes. Balcony meeting room.",
    "bodyucs2":"005300740061006600660020006D0065006500740069",
    "bodygsm7":"5374616666206D656574696E672069",
    "uniqueid":"75F3FAB"
    "senderid":"MyCompany",
    "senderidenabled":true,
    "unicode":false,
    "numchars":62,
    "escapenumchars":0,
    "smscount":1,
    "subscribers":79,
    "charge":3.212,
    "balance":752.121
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
groupkey Eindeutiger Schlüssel für dieses Mailing. Sollte auf Client-Seite zur späteren Referenz (Sendeberichte) gespeichert werden. string(32)
body Der SMS-Inhalt als Unicode Text-String string
bodyucs2 Der SMS-Inhalt in UCS2 Bytecode-Notation string
bodygsm7 Der SMS-Inhalt in GSM7 Bytecode-Notation (oder NULL falls die Nachricht als Unicode versendet wurde) string || NULL
uniqueid string(7)
senderid Zeigt an ob die Ziel-Rufnummer dynamische Senderkennungen unterstützt boolean
unicode Zeigt an ob die Nachricht als Unicode oder GSM verschickt wurde boolean
numchars Zeigt an wieviele Zeichen für die SMS verwendet wurden integer
escapenumchars Zeigt an wieviele Zeichen escaped werden mussten (und als zwei Zeichen im GSM Format zählten) integer
smscount Zeigt an ob die Nachricht zu einer langen SMS zusammengefasst wurde und aus wievielen SMS-Längen sie besteht integer
subscribers Die Anzahl der Empfänger dieses Mailings. integer
charge Zeigt an wieviel für diese SMS berechnet wurde float
balance Zeigt das Rest-Guthaben im verwendeten Konto an float

Funktionsspezifische API Fehler

Fehlercode Fehlerbeschreibung
220 Ungültige Unique ID
Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Funktion: addSubscriber

Fügt der Mailing-Liste einen neuen Abonennten hinzu. Falls die übergebene Rufnummer bereits in der List existiert wird der bestehende Eintrag überschrieben.
Gibt ein JSON Objekt mit einer Bestätigung oder Fehlermeldung zurück.

POST/GET Beispiel

username=xxx&password=yyyy&function=addSubscriber &uniqueid=75F3FAB&number=+1230987654321&title=Ms&firstname=Marylin &lastname=Monroe&company=Hollywood

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"addSubscriber",
    "uniqueid":"75F3FAB",
    "number":"+1230987654321",
    "title":"Ms",
    "firstname":"Marylin",
    "lastname":"Monroe",
    "company":"Hollywood"
}

Erforderliche Parameter

Parameter Beschreibung Typ
number Rufnummer im internationalen Format. Zum Beispiel: +49123456789, 49123456789 oder 0049123456789 string
uniqueid Die Unique ID der Mailing-Liste. Die Unique IDs für alle Mailing-Listen können im Web Interface unter "Verwalten" der jeweiligen Mailing-Liste eingesehen werden. string

Optionale Parameter

Parameter Beschreibung Typ
title Anrede des Abonennten varchar(16)
firstname Vorname des Abonennten varchar(32)
lastname Nachname des Abonennten varchar(32)
company Firma des Abonennten varchar(64)

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "number":"+1230987654321"
    "title":"Ms",
    "firstname":"Marylin",
    "lastname":"Monroe",
    "company":"Hollywood",
    "subscribercost":0.019,
    "senderidenabled":true,
    "maxcharsgsm":765,
    "maxcharsunicode":335,
    "countrycode":"US",
    "mailinglistcost":1.213
    "mailinglistsubscribers":74
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
number Normalisierte Rufnummer der neuen Abonennten string
title Anrede des neuen Abonennten string
firstname Vorname des neuen Abonennten string
lastname Nachname des neuen Abonennten string
company Firma des neuen Abonennten string
subscribercost Kosten pro Nachricht an diesen Abonennten float
senderidenabled Zeigt an ob die Ziel-Rufnummer dynamische Senderkennung unterstützt boolean
maxcharsgsm Zeigt an wieviele Zeichen pro Nachricht an diesen Abonenntent verschickt werden können integer
maxcharsunicode Zeigt an ob die Rufnummer des Abonennten Unicode Nachrichten unterstützt integer
countrycode Das Länderkürzel des Abonennten (Zwei Buchstaben ISO-Standard Format) string(2)
mailinglistcost Die neuen Gesamtkosten pro Mailing an diese Liste. float
mailinglistsubscribers Die neue Anzahl von Abonennten auf dieser Mailing-Liste. integer

Funktionsspezifische API Fehler

Fehlercode Fehlerbeschreibung
221 Eingabe für {field} is zu lang.
Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Funktion: updateSubscriber

Siehe Funktion: addSubscriber

Funktion: deleteSubscriber

Entfernt einen Abonennten aus der Mailing-Liste. Verwendet die Rufnummer als Referenz-Schlüssel.
Gibt ein JSON Objekt mit einer Bestätigung oder Fehlermeldung zurück.

POST/GET Beispiel

username=xxx&password=yyyy&function=deleteSubscriber &uniqueid=75F3FAB&number=+1230987654321

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"deleteSubscriber",
    "uniqueid":"75F3FAB",
    "number":"+1230987654321"
}

Erforderliche Parameter

Parameter Beschreibung Typ
uniqueid Die Unique ID der Mailing-Liste. Die Unique IDs für alle Mailing-Listen können im Web Interface unter "Verwalten" der jeweiligen Mailing-Liste eingesehen werden. string
number Die Rufnummer des zu löschenden Abonennten string

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "number":"+1230987654321"
    "mailinglistcost":1.213
    "mailinglistsubscribers":74
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
number Die normalisierte Rufnummer des gelöschten Abonennten string
mailinglistcost Die neuen Gesamtkosten pro Mailing an diese Liste. float
mailinglistsubscribers Die neue Anzahl von Abonennten auf dieser Mailing-Liste. integer

Funktionsspezifische API Fehler

Fehlercode Fehlerbeschreibung
220 Ungültige Unique ID
222 Die Mailing-Liste enthält keinen Abonennten mit dieser Rufnummer
Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Werkzeuge API

Funktion: doHlrLookup

Führt einen Home Location Resgister (HLR) Lookup für einen Rufnummer aus und gibt die relevanten MSC, MCC, MNC, INSI sowie Informationen über den Mobilfunkbetreiber zurück und gibt an ob die Rufnummer derzeit Roaming ist (das Telefon sich im Ausland befindet) und ob es sich um eine portierte Nummer handelt (die urprünglich bei einem anderen Mobilfunkbetreiber registriert war).
Hinweis: Erfahre mehr über HLR, IMSI, MCC, MNC und MSC.

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"doHlrLookup",
    "number":"+491234567890"
}

Erforderliche Parameter

Parameter Beschreibung Typ
number Die Rufnummer für die der HLR Lookup ausgeführt werden soll. Internationales Format, zum Beispiel: 49123456789 oder +49123456789 oder 0049123456789 string

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "status":"HLR_STATUS_OK",
    "number":"+49178873xxxxx",
    "imsi":"262031350393955",
    "mcc":"262",
    "mnc":"03",
    "msin":"1350393955",
    "servingmsc":"88693542",
    "servinghlr":"491770112000",
    "originalnetworkname":"E-Plus",
    "originalnetworkprefix":"178",
    "originalcountryname":"Germany",
    "originalcountrycode":"DE",
    "originalcountryprefix":"+49",
    "roamingcountryname":"Taiwan",
    "roamingcountrycode":"TW",
    "roamingcountryprefix":"+886",
    "roamingnetworkname":"Taiwan Mobile",
    "portednetworkname": null,
    "isported":false,
    "iscorrect":true,
    "isroaming":true,
    "charge":0.010
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
status Zeigt den Status des Lookups an. Bitte verwende die HLR Status-Referenz für weitere Informationen. string
number Die Rufnummer für die der HLR Lookup ausgeführt wurde. string
imsi International Mobile Subscriber Identity (IMSI). Eindeutige ID der Rufnummer (befindet sich auf der SIM Karte). string
mcc Der Mobile Countrz Code (MCC) string
mnc Der Mobile Network Code (MNC). Kann entweder zwei Zeichen (Europäischer Standard) oder drei Zeichen (Nord-Amerikanischer Standard) enthalten. string
msin Die Mobile Subscription Identification Number (MSIN) in der Kundendatenbank des Mobilfunkbetreibers zu dem diese Rufnummer gehört. string
servingmsc Das Mobile Switching Center (MSC) über die SMS an diese Rufnummer geroutet werden. string
servinghlr Das Home Location Register (HLR) in dem die Rufnummer abgelegt ist. string
originalnetworkname Der Mobilfunkbetreiber zu dem diese Rufnummer gehört (oder ursprünglich gehört hat, falls es sich hierbei um eine portierte Nummer handelt). string
originalnetworkprefix Die Vorwahl des Mobilfunknetzwerkes zu dem diese Nummer gehört (oder ursprönglich gehört hat, falls es sich um eine portierte Nummer handelt). string
originalcountryname Das Land zu dem diese Rufnummer gehört. string
originalcountrycode Das ISO-Länderkürzel (zwei Zeichen) zu dem diese Rufnummer gehört. string
originalcountryprefix Die Vorwahl des Landes zu dem diese Rufnummer gehört. string
roamingcountryname Das Land in dem diese Rufnummer derzeit gehostet wird (Roaming). string
roamingcountrycode Das ISO-Länderkürzel (zwei Zeichen) des Landes in dem diese Rufnummer derzeit gehostet wird (Roaming). string
roamingcountryprefix Die Vorwahl des Landes in dem diese Rufnummer derzeit gehostet wird (Roaming). string
roamingnetworkname The network the cell phone is currently roaming with string
portednetworkname The network the number has been ported to string
isported Zeigt an ob es sich um eine portiere Nummer handelt boolean
iscorrect Zeigt an ob die angegebene Rufnummer gültig ist boolean
isroaming Zeigt an ob diese Rufnummer derzeit in einem Gastland gehostet wird (Roaming). boolean
charge Die Kosten die für diesen HLR Lookup berechnet wurden (0.01 EUR). numeric
Hinweis: Erfahre mehr über HLR, IMSI, MCC, MNC und MSC.

Funktionsspezifische API Fehler

Fehlercode Fehlerbeschreibung
210 Die Rufnummer scheint ungültig zu sein
226 HLR Lookup fehlgeschlagen.
Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

HLR Status-Referenz

Status Beschreibung
HLR_STATUS_UNKNOWN_NUMBER Die Nummer existiert nicht oder konnte in keinem HLR gefunden werden. SMS an diese Rufnummer kommen nicht an.
HLR_STATUS_OK Diese Nummer existiert und der HLR Lookup war erfolgreich. SMS an diese Rufnummer werden normal zugestellt.
HLR_STATUS_NOT_OK Die Rufnummer befindet sich seit langer Zeit ausser Netzwerk-Reichweite oder wurde vom Mobilfunkbetreiber deaktiveiert. SMS an diese Rufnummer können nicht zugestellt werden.
HLR_STATUS_FAILED HLR Lookup fehlgeschlagen.
HLR_STATUS_AWAITING_RESPONSE Awaiting response from HLR.

Funktion: toUCS2

UCS2-kodiert einen String
Wichtig: toUCS2 muss über JSON aufgerufen werden.

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"toUCS2",
    "str":"繁体中文"
}

Erforderliche Parameter

Parameter Beschreibung Typ
number Die Rufnummer für die der HLR Lookup ausgeführt werden soll. Internationales Format, zum Beispiel: 49123456789 oder +49123456789 oder 0049123456789 string

Optionale Parameter

Parameter Beschreibung Typ

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "ucs2":"7E414F534E2D6587"
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
ucs2 Der übergebene String in UCS2-Notation string

Funktionsspezifische API Fehler

Kein(e)
Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Funktion: fromUCS2

Dekodiert einen UCS2 String

POST/GET Beispiel

username=xxx&password=yyyy&function=fromUCS2 &str=0048006100760065002000610020006E00690063006500200064

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"fromUCS2",
    "str":"7E414F534E2D6587"
}

Erforderliche Parameter

Parameter Beschreibung Typ
str Der zu dekodierende UCS2 String string

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "decoded":"繁体中文"
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
decoded Der dekodierte UCS2 String in Unicode string

Funktionsspezifische API Fehler

Fehlercode Fehlerbeschreibung
201 Ungültige UCS2 Eingabe
Hinweis: Bitte beachte auch den Abschnitt über Allgemeine Fehler

Funktion: normalizeNumber

Normalizes a cell phone number in loose format into international standard MSISDN format. For example from +1(712)543-2321 into +17125432321

POST/GET Beispiel

username=xxx&password=yyyy&function=normalizeNumber&number=001(712)736-3423

JSON Beispiel

{
    "username":"xxx",
    "password":"yyy",
    "function":"normalizeNumber",
    "number":"001(712)736-3423"
}

Erforderliche Parameter

Parameter Beschreibung Typ
number The phone number to normalize. Loose format, e.g. 00491787654321, 0049(178)765-4321 etc. string

Antwort bei einem erfolgreichen Aufruf

{
    "success":true,
    "number":"+17127363423",
    "countrycode":"US"
}

Rückgabewerte bei einem erfolgreichen Aufruf

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
number The normalized number in international MSISDN standard format. string
countrycode The corresponding country code (international two-character ISO format) string(2)

Funktionsspezifische API Fehler

Fehlercode Fehlerbeschreibung
237 The number could not be normalized.

Fehlerberichte

All API errors responses have a standardized JSON structure with a success, errorcode and errordescription attribute.

Antwort bei einem fehlerhaften Aufruf

{
    "success":false,
    "errorcode":103,
    "errordescription":"Ein erforderlicher Parameter fehlt: senderid"
}

Rückgabewerte bei einem fehlerhaften Aufruf

Schlüssel Beschreibung Typ
success Zeigt an ob der Aufruf erfolgreich bearbeitet werden konnte. boolean
errorcode Fehlercode (bestehend aus drei Nummern) string(3)
errordescription Fehlerbeschreibung string

Funktionsspezifische API Fehler

Manche Funktionen haben spezifische Fehlercodes die nur von der jeweiligen Funktion zurückgegeben werden. Diese Art von Fehlercode hat das Format 2xx und ist in der Dokumentation für die jeweilige Funktion beschrieben.

Allgemeine API Fehler

Jede Funktion kann Funktionsspezifische Fehler, aber auch allgemeine API Fehler mit dem Fehlercode-Format 1xx, zurückgeben.

Allgemeine Fehlercodes

Fehlercode Fehlerbeschreibung
101 Login fehlgeschlagen. Falscher Benutzername oder Passwort.
102 Dieser Account wurde noch nicht freigeschaltet.
103 Ein erforderlicher Parameter fehlt
104 Ungültiger Aufruf. Keine GET, POST oder gültige JSON Eingabe gefunden.
105 Unbekannte Funktion
106 Zugriff verweigert
107 Allgemeiner API Fehler
108 Ungültige Aufrufs-Struktur
109 Guthaben reicht nicht aus
Haben wir etwas vergessen? Gibt es Fragen? Vorschläge oder Ideen was noch hinzugefügt werden sollt? Fall ja, lass es uns bitte wissen!
© My-Cool-Webservices Ltd. 2008-2014
English
Español
Français
Nederlands
Polski
Português
Руccкий
繁体中文