Spezifikation

SENDLY SMS API

Spezifikation v1.2

Die SENDLY SMS API funktioniert durch die Übertragung von Nachrichten über das HTTP-Protokoll. Für die Verarbeitung von SMS-Nachrichten stehen zwei sich gegenseitig ausschließende Modi zur Verfügung: SMS API und 3CX API

1. SMS API

1.1 Nachricht senden

Dies ist der Standardmodus der API, gedacht für den Einsatz mit Anwendungen, die REST API unterstützen. Für den SMS-Versand steht folgender Endpunkt zur Verfügung:

POST https://api.sendly.link/api/sms

Autorisierung: Bearer token
Erwarteter Inhaltstyp: application/json

Felder des Anfragekörpers:

Feld	Datentyp	Beschreibung
`from`	Numerische Zeichenkette, minimum 9 Zeichen, maximum 11 Zeichen (optionales Feld)	Die virtuelle Mobilnummer in SENDLY
`to`	Numerische Zeichenkette, minimum 9 Zeichen, maximum 11 Zeichen	Ziel-Mobilnummer
`body`	Zeichenkette, minimum 1 Zeichen	Nachrichtentext

Beispielanfrage:

curl -X POST https://api.sendly.link/api/sms \
     -H "Authorization: Bearer TWOJ_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "from": "48732129000",
           "to": "48732129001",
           "body": "Test SENDLY"
         }'

Der Token kann im Kundenpanel generiert und heruntergeladen werden. Alternativ kann der Token über den Kundenservice bezogen werden.

Mögliche Antworten:

200 – die Nachricht wurde zum Versand angenommen

Antwortkörper:

Feld	Datentyp	Beschreibung
`message_id`	Zeichenkette	Eindeutige Nachrichtenkennung (16 Hex-Zeichen)

Beispielantwort:

{"message_id":"a906cff7719bd889"}

Mögliche Fehlerantworten:

403 – Autorisierungsproblem
422 – Problem bei der Datenvalidierung
429 – Anfragelimit überschritten

Im Fehlerfall kann der Antwortkörper eines oder mehrere der in der Tabelle unten beschriebenen Felder enthalten:

Feld	Datentyp	Beschreibung
`errors.token`	Array von Zeichenketten	Beschreibung des Fehlers im Zusammenhang mit dem übergebenen Zugriffstoken
`errors.from`	Array von Zeichenketten	Beschreibung des Fehlers im Zusammenhang mit der Quellnummer
`errors.to`	Array von Zeichenketten	Beschreibung des Fehlers im Zusammenhang mit der Zielnummer
`errors.body`	Array von Zeichenketten	Beschreibung des Fehlers im Zusammenhang mit dem Nachrichtentext

Beispielantwort:

{"errors":{"token":["Invalid token"]}}

Ausgehende Nachrichten werden in UCS-2 kodiert und alle 60 Zeichen geteilt. Optional ist der SMS-Versand in GSM7-Kodierung möglich, begrenzt auf eine einzelne Nachricht mit einer maximalen Länge von 160 Zeichen. Diese Option kann im Kundenpanel oder auf Anfrage beim Kundenservice aktiviert werden.

1.2 Nachricht an mehrere Nummern senden

Dies ist eine API-Methode, die den Versand derselben Nachricht an mehrere Nummern ermöglicht. Die Aktivierung dieser Funktion für einen Zugriffstoken erfolgt ausschließlich über den Kontakt mit dem Kundenservice. Folgender Endpunkt steht zur Verfügung:

POST https://api.sendly.link/api/sms-multi

Autorisierung: Bearer token
Erwarteter Inhaltstyp: application/json

Felder des Anfragekörpers:

Feld	Datentyp	Beschreibung
`from`	Numerische Zeichenkette, minimum 9 Zeichen, maximum 11 Zeichen (optionales Feld)	Die virtuelle Mobilnummer in SENDLY
`to`	Array numerischer Zeichenketten, minimum 9 Zeichen, maximum 11 Zeichen, minimum 1 Element, maximum 100 Elemente	Ziel-Mobilnummern
`body`	Zeichenkette, minimum 1 Zeichen	Nachrichtentext

Beispielanfrage:

curl -X POST https://api.sendly.link/api/sms-multi \
     -H "Authorization: Bearer TWOJ_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "from": "48732129000",
           "to": ["48732129001", "48732129002"],
           "body": "Test SENDLY"
         }'

Die Validierung der übermittelten Telefonnummern erfolgt nach dem Prinzip „alles oder nichts“ – jede der übermittelten Nummern muss eine gültige polnische Mobilnummer sein, sonst wird die gesamte Anfrage abgelehnt. Die übermittelten Nummern müssen eindeutig sein; das Übermitteln doppelter Nummern führt zur Ablehnung der gesamten Anfrage.

Mögliche Antworten:

200 – die Nachricht wurde zum Versand angenommen

Antwortkörper:

Feld	Datentyp	Beschreibung
`message_ids`	Array von Objekten	Jedes zurückgegebene Objekt enthält ein Feld „number“, das auf eine der angegebenen Zielnummern verweist, sowie „message_id“, die Kennung der zum Versand angenommenen Nachricht

Beispielantwort:

{"message_ids":[{"number":"48732129001","message_id":"a906cff7719bd889"}]}

Mögliche Fehlerantworten:

403 – Autorisierungsproblem
422 – Problem bei der Datenvalidierung
429 – Anfragelimit überschritten

Im Fehlerfall kann der Antwortkörper eines oder mehrere der in der Tabelle unten beschriebenen Felder enthalten:

Feld	Datentyp	Beschreibung
`errors.token`	Array von Zeichenketten	Beschreibung des Fehlers im Zusammenhang mit dem übergebenen Zugriffstoken
`errors.from`	Array von Zeichenketten	Beschreibung des Fehlers im Zusammenhang mit der Quellnummer
`errors.to`	Array von Zeichenketten	Beschreibung des Fehlers im Zusammenhang mit der Zielnummer
`errors.body`	Array von Zeichenketten	Beschreibung des Fehlers im Zusammenhang mit dem Nachrichtentext

Beispielantwort:

{"errors":{"token":["Invalid token"]}}

1.3 Nachrichten empfangen

Eingehende Nachrichten werden an den im Kundenpanel angegebenen Webhook gesendet. Der Webhook kann auch per Anfrage an den Kundenservice angegeben werden. Es wird ein einziger Zustellversuch unternommen. Die API-Anfrage folgt keinen Weiterleitungen und authentifiziert sich nicht gegenüber dem Webhook. Die Anfrage stammt von der aktuellen IP-Adresse der Domain api.sendly.link.

Methode: POST
Inhaltstyp: application/json

Felder des Anfragekörpers:

Feld	Datentyp	Beschreibung
`type`	Zeichenkette	Nachrichtentyp. Für eine eingehende Nachricht nimmt er den Wert „MESSAGE“ an
`from`	Zeichenkette	Darstellung der Quellnummer. Bei einer Nachricht mit überschriebener Nummer enthält dieses Feld die Absender-ID (nadpis).
`to`	Numerische Zeichenkette	Ziel-Telefonnummer
`body`	Zeichenkette	Nachrichtentext

Beispiel-Anfragekörper:

{"type":"MESSAGE","from":"48732129000","to":"48732129001","body":"Test sms"}

1.4 Zustellbestätigung

Wenn Sie Zustellbenachrichtigungen erhalten möchten, müssen Sie diese Option im Kundenpanel oder per Anfrage an den Kundenservice aktivieren. Die Aktivierung dieser Option bewirkt, dass eine Anfrage an die angegebene Webhook-Adresse gesendet wird. Es wird ein einziger Zustellversuch der Benachrichtigung unternommen. Die API-Anfrage folgt keinen Weiterleitungen und authentifiziert sich nicht gegenüber dem Webhook. Die Anfrage stammt von der aktuellen IP-Adresse der Domain api.sendly.link.

Methode: POST
Inhaltstyp: application/json

Felder des Anfragekörpers:

Feld	Datentyp	Beschreibung
`type`	Zeichenkette	Nachrichtentyp. Für eine Statusnachricht nimmt er den Wert „NOTIFICATION“ an
`message_id`	Zeichenkette	Die nach der Annahme zum Versand zurückgegebene Nachrichtenkennung
`status`	Zeichenkette	DELIVERED für eine Zustellbenachrichtigung. ERROR für eine Fehlerbenachrichtigung.

Beispiel-Anfragekörper:

{"type":"NOTIFICATION","message_id":"a906cff7719bd889","status":"DELIVERED"}

2. 3CX SMS API

Diese Version der API unterstützt das Senden und Empfangen von Nachrichten auf Basis der aktuellen Spezifikation des 3CX Phone System. Um diese API zu aktivieren, wählen Sie im Kundenpanel beide Optionen: SMS API und 3CX SMS API.

Für ausgehenden Verkehr müssen Sie im SMS-Bereich in 3CX den im Kundenpanel generierten Token sowie die URL angeben:

https://api.sendly.link/api/tcx

Um eingehende Nachrichten zu verarbeiten, geben Sie im Kundenpanel den in Ihrer 3CX-Anlage verfügbaren Webhook an.

Die Aktivierung kann auch der Kundenservice vornehmen; in diesem Fall geben Sie den Webhook an und erhalten als Antwort einen Token.