SMS

Nutzen Sie diese API zum Versand von SMS mit zahlreichen Funktionen an einen oder mehrere Empfänger gleichzeitig.

POST/api/sms

SMS versenden

Versenden Sie eine SMS an einen oder mehrere Empfänger.

  • Name
    to
    Type
    string
    Description

    Empfängernummer der SMS. Dies kann auch der Name eines Kontakts oder einer Gruppe sein. Unsere API akzeptiert alle gängigen Format wie 0049171999999999, 49171999999999, +49171999999999. Mehrere Empfänger werden kommagetrennt übergeben. Idealerweise geben Sie die Rufnummer im internationalen Format nach E.164 an.

  • Name
    text
    Type
    string
    Description

    Text der SMS Nachricht.

  • Name
    from
    Type
    string
    Optional
    Optional
    Description

    Absender der SMS. Dieser darf maximal 11 alphanumerische oder 16 numerische Zeichen enthalten.

  • Name
    delay
    Type
    timestamp
    Optional
    Optional
    Description

    Datum/Zeit für zeitversetzten Versand. Wahlweise Unix-Timestamp oder ein Zeitstempel im Format JJJJ-MM-TT hh:mm:ss.

  • Name
    flash
    Type
    boolean
    Optional
    Optional
    Description

    SMS als Flash SMS versenden. Diese werden direkt im Display des Empfängers angezeigt. Auf den meisten Endgeräten wird bei Flash-SMS kein Absender angezeigt, außer bei einigen älteren Modellen.

  • Name
    udh
    Type
    string
    Optional
    Optional
    Description

    Individueller User Data Header (UDH) der SMS. Sofern angegeben und Variable text Hexcode enthält, wird die Nachricht als 8-bit Binary SMS versendet. 050003CC0201 (Verkettete Nachricht: Referenznummer 204, Teil 1 von 2)

  • Name
    ttl
    Type
    integer
    Optional
    Optional
    Description

    Gibt die Validity Period (Gültigkeitsdauer) der SMS in Minuten an. Der Standard liegt bei 2880, also 48 Stunden. Bitte beachten Sie, dass nicht alle Netze eine abweichende Einstellung zulassen.

  • Name
    label
    Type
    integer
    Optional
    Optional
    Description

    Setzen Sie optional für jede SMS ein eigenes Label, um diese in Ihren Statistiken zuordnen zu können. Max. 100 Zeichen, erlaubte Zeichen: a-z, A-Z, 0-9, .-_@.

  • Name
    performance_tracking
    Type
    boolean
    Optional
    Optional
    Description

    Klick und Performance Tracking für im SMS Text gefundene URLs aktivieren. Damit wird gleichzeitig der URL Kürzer aktiviert.

  • Name
    foreign_id
    Type
    string
    Optional
    Optional
    Description

    Geben Sie Ihre eigene ID für diese Nachricht an. Sie erhalten die foreign_id wiederum zurück bei Callbacks für Statusberichte etc. Max. 64 Zeichen, erlaubte Zeichen: a-z, A-Z, 0-9, .-_@.

  • Name
    unicode
    Type
    string
    Veraltet
    Veraltet
    Description

    Versand als Unicode SMS (kyrillisch, arabische etc Schriftzeichen). Die SMS Länge verkürzt sich dadurch auf 70 Zeichen. Bitte beachten Sie, dass unser Gatway die Kodierung automatisch erkennt. Dieser Parameter ist daher nicht notwendig. Sie können hiermit allerdings eine bestimmte Versandart forcieren.

  • Name
    utf8
    Type
    string
    Veraltet
    Veraltet
    Description

    Forciert die Erkennung als UTF8 Zeichensatz und überschreibt die automatische Erkennung der API.

  • Name
    return_msg_id
    Type
    string
    Veraltet
    Veraltet
    Description

    Ist dieser Parameter gesetzt, wird in in der zweiten Zeile nach dem Statuscode die ID der SMS ausgegeben. Hat keine Auswirkung, wenn der Parameter json auf 1 gesetzt ist.

  • Name
    details
    Type
    string
    Veraltet
    Veraltet
    Description

    Zeigt zahlreiche Details zur verschickten SMS an. Praktisch zum Debugging. Hat keine Auswirkung, wenn der Parameter json auf 1 gesetzt ist.

  • Name
    json
    Type
    string
    Veraltet
    Veraltet
    Description

    Die Ausgabe erfolgt detaillierter im JSON-Format. Bitte verwenden Sie stattdessen Accept: application/json im Header.

  • Name
    no_reload
    Type
    string
    Veraltet
    Veraltet
    Description

    Reloadsperre ausschalten. Diese Sperre verhindert den Versand von gleichen SMS (Text & Empfänger gleich) innerhalb von 180 Sekunden. Diese Sperre können Sie auch dauerhaft in Ihrem Login unter Einstellungen > SMS deaktivieren.

Anfrage

POST
/api/sms
curl -X POST https://gateway.seven.io/api/sms \
  -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -d "to=49176123456789" \
  -d "from=AcmeInc" \
  -d "text=hello world"

Antwort

{
"success": "100",
"total_price": 0.075,
"balance": 593.994,
"debug": "false",
"sms_type": "direct",
"messages": [
  {
    "id": "77229318510",
    "sender": "sender",
    "recipient": "49123456789",
    "text": "Hello World",
    "encoding": "gsm",
    "label": null,
    "parts": 1,
    "udh": null,
    "is_binary": false,
    "price": 0.075,
    "success": true,
    "error": null,
    "error_text": null
  },
  {
    "id": "77229318511",
    // ....
  }
]
}

Dateianhänge

Sie können zusätzlich direkt per API Dateianhänge in Ihren SMS versenden. Hierzu müssen den Parameter files als assoziatives Array die jeweiligen Dateien übergeben werden.

Eigenschaften

  • Name
    name
    Type
    string
    Description

    Dateiname. Dieser muss exakt so im SMS Text als Platzhalter eingefügt werden. Hier wäre es [[dokument.pdf]]

  • Name
    contents
    Type
    string
    Description

    Inhalt der Datei als base64 kodiert.

Optionale Eigenschaften

  • Name
    validity
    Type
    integer
    Description

    Gültigkeit in Tagen. Nach der Gültigkeitsdauer wird die Datei automatisch gelöscht. Standard: 3

  • Name
    password
    Type
    string
    Description

    Gewünschtes Zugangspasswort zu der Datei. Ohne Passwort ist die Datei für jeden mit dem Link einsehbar.

Anfrage

POST
/api/sms
curl -X POST https://gateway.seven.io/api/sms \
 -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
 -H "Accept: application/json" \
 -d "to=49176123456789" \
 -d "from=AcmeInc" \
 -d "text=Hallo, hier das Dokument: [[dokument.pdf]]" \
 -d "files[0][name]=dokument.pdf" \
 -d "files[0][content]=iVBORw0KGgoAAAANSUhEUgAAAdoAAACWCAYAAAB5CUk..."

Rückgabecodes

Für jede SMS erhalten Sie einen Rückgabecode in der Antwort, der detailliert Informationen über den Versand bzw. den Fehler beim Versand der SMS angibt.

  • Name
    100
    Description

    SMS wurde vom Gateway angenommen und wird versendet.

  • Name
    101
    Description

    Versand an mindestens einen Empfänger fehlgeschlagen.

  • Name
    201
    Description

    Absender ungültig. Erlaubt sind max 11 alphanumerische oder 16 numerische Zeichen.

  • Name
    202
    Description

    Die Empfängernummer ist ungültig.

  • Name
    301
    Description

    Parameter to nicht gesetzt.

  • Name
    305
    Description

    Parameter text nicht gesetzt.

  • Name
    401
    Description

    Parameter text ist zu lang.

  • Name
    402
    Description

    Diese SMS wurde innerhalb der letzten 180 Sekunden bereits verschickt. Sie können diese Sperre in Ihren Accounteinstellungen deaktivieren.

  • Name
    403
    Description

    Maximales Limit pro Tag für diese Empfängernummer erreicht.

  • Name
    500
    Description

    Account hat zu wenig Guthaben für den Versand dieser SMS.

  • Name
    600
    Description

    Es ist ein Fehler beim Versand aufgetreten.

  • Name
    900
    Description

    Authentifizierung ist fehlgeschlagen. Bitte prüfen Sie den in der Authentifizierung verwendeten API Schlüssel.

  • Name
    901
    Description

    Verifizierung des Signierhashes ist fehlgeschlagen.

  • Name
    902
    Description

    Der API Schlüssel hat kein Zugriffsrecht auf diesen Endpunkt.

  • Name
    903
    Description

    Die IP, von der aus die Anfrage ausgeführt wurde, ist nicht in der Liste erlaubter IP Adressen enthalten.

DELETE/api/sms

SMS löschen

Löschen Sie eine oder mehrere SMS, bevor diese versendet wurden, um den Versand zu verhindern.

  • Name
    ids
    Type
    array
    Description

    Eine Liste der zu löschenden SMS. Geben Sie hier die jeweiligen ´id´s der SMS an, die gelöscht werden sollen.

Anfrage

DELETE
/api/sms
curl -X DELETE "https://gateway.seven.io/api/sms" \
  -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
  -H "Content-type: application/json" \
  -d "{ \"ids\": [ 77150850625, 77150850626 ] }"

Antwort

{
  "success": true,
  "deleted": [
    "77150850625",
    "77150850626"
  ]
}

Legacy

Aus Kompatibilitätsgründen werden weiterhin ältere Zugriffsmethoden in simplerer Art unterstützt. Bitte beachten Sie, dass neue Features hauptsächlich für die aktuelle API veröffentlicht werden. Außerdem kann die folgende Verwendung zu Problemen mit größeren Anfragen und zu Sicherheitsproblemen führen.

Beispiele

Die folgende Anfrage folgender URL sendet eine SMS mit dem Inhalt meine erste nachricht als SMS mit dem Absender seven.io an die Rufnummer 49160999999999:

Anfrage

GET
/api/sms
curl "https://gateway.seven.io/api/sms?p=IHR_API_SCHLÜSSEL&to=49160999999999&text=meine%20erste%20nachricht&from=seven.io&return_msg_id=1"

Antwort

100
123456789

Diese Anfrage zeigt zahlreiche Details zu der Nachricht, jeweils getrennt durch einen Zeilenumbruch:

Anfrage

GET
/api/sms
curl "http://gateway.seven.io/api/sms?p=IHR_API_SCHLÜSSEL&to=Gruppe1&text=Test+SMS&from=SMS&flash=0&details=1"

Antwort

100
Verbucht: 0.075
Preis: 0.075
Guthaben: 27.38
Text: Test SMS
SMS-Typ: direct
Flash SMS: off
Encoding: ASCII
GSM0338: true
Debug: false