Transaktions-SMS – Spezifikation (Advanced API)

Vorsicht

Es ist strengstens untersagt, transaktionale SMS für Werbe- oder Marketingzwecke zu missbrauchen. Sie dürfen ausschließlich zur Benachrichtigung verwendet werden – als SMS-Benachrichtigung.

Hinweis

Möchten Sie eine Massenbenachrichtigung über die transaktionale Route versenden, wenden Sie sich bitte an unseren Support. Aus triftigem Grund können wir diese Möglichkeit freischalten.

API-URL

URL zum Senden der HTTP-Anfragen:

https://portal.bulkgate.com/api/2.0/advanced/transactional

Hinweis

Erreicht die Anfrage ihr Ziel nicht, wiederholen Sie sie auf dem Backup-Server backup1.bulkgate.com.

Unterstützte HTTP-Methoden

POST - application/json

POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json

Parametertabelle

PARAMETERNAME	WERT	PFLICHT	STANDARDWERT
application_id	Anwendungs-ID	Ja	-
application_token	Authentifizierungstoken der Anwendung	Ja	-
number	Nummer des Empfängers oder Array von Empfängernummern – Wert number	Ja oder `admin`	-
admin	Nummer des BulkGate-Administrators, der die Benachrichtigung erhält. Mehr Informationen	Ja oder `number`	-
text	Text der SMS-Nachricht (max. 612 Zeichen bzw. 268 Zeichen bei Verwendung von Unicode), UTF-8-Kodierung. In die Vorlage können Variablen aus dem Array `variables` (weiterer Parameter) eingefügt werden: `Hello <first_name> <last_name> ....`	Ja	-
variables	Assoziatives Array zum Einfügen von Variablen in den Text, z. B.: `{"first_name": "John", "last_name": "Doe"}`	Nein	`[]`
channel	Alternative Kanäle. Die Kanäle werden in einer Kaskade durchlaufen, und zwar in der Reihenfolge, in der Sie sie im Objekt aufführen – können wir Ihre Nachricht über den ersten Kanal nicht zustellen, wird der nächste in der Liste verwendet. SMS wird nicht automatisch angehängt; möchten Sie sie als letzte Ausweichoption nutzen, nehmen Sie das Objekt `sms` in die Kaskade auf. Ist gar kein Kanal angegeben, wird die Nachricht als SMS versendet.	Nein	SMS-Objekt
country	Geben Sie die Empfängernummern im internationalen Format an (mit Vorwahl, z. B. `420`) oder fügen Sie den Ländercode im Format ISO 3166-1 alpha-2 hinzu (`777777777` + `CZ` = `420777777777`). Siehe die Beispielanfrage mit Land. Ist der Wert `null`, wird die Angabe anhand der eingestellten Zeitzone ergänzt.	Nein	`null`
schedule	Planen Sie Datum und Uhrzeit des Versands als Unix-Zeitstempel oder im Format ISO 8601.	Nein	Sofort
duplicates_check	Wählen Sie `on`, um den Versand doppelter Nachrichten an dieselbe Telefonnummer zu verhindern. Nachrichten mit demselben Text an dieselbe Nummer werden entfernt, wenn zwischen ihnen weniger als 5 Minuten liegen. Bei `off` werden keine Duplikate entfernt.	Nein	`off`
tag	Kennzeichnung der Nachricht, über die der Benutzer sie später wiederfinden kann.	Nein	-

Wert `number`

Der Wert number kann wie folgt angegeben werden:

Array von Telefonnummern

[ "420777777777", "420888888888", "420999999999" ]

Kanäle

Das Objekt channel legt fest, über welche Kanäle und in welcher Reihenfolge die Nachricht versendet wird. Die Reihenfolge der Schlüssel in Ihrer Anfrage ist die Reihenfolge der Kaskade, und SMS wird nicht automatisch angehängt – siehe Kanalkaskade.

SCHLÜSSEL	KANALOBJEKT
`sms`	SMS
`viber`	Viber – transaktional
`rcs`	RCS
`whatsapp`	WhatsApp

Beispielanfrage

POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": ["777777777", "777777778"], "text": "Beispieltext <first_name>", "variables": {"first_name": "John"}, "country": "cz", "schedule": "2023-08-14T18:30:00-01:00", "channel": { "whatsapp": { "sender": "420777777777", "expiration": 300, "message": { "text": "text" } }, "rcs": { "sender": "BulkGate", "expiration": 300, "message": { "text": "text" } }, "viber": { "sender": "BulkGate", "expiration": 100 }, "sms": { "sender_id": "gText", "sender_id_value": "Mr. Sender", "unicode": true } } }

Antwort

Bei Erfolg:

{ "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0, "duplicity_message": 0 } }, "response": [ { "status": "scheduled", "message_id": "transactional-64afe5f28ffc2-0", "part_id": [ "transactional-64afe5f28ffc2-0" ], "number": "420777777777", "channel": "viber" }, { "status": "scheduled", "message_id": "transactional-64afe5f28ffc2-1", "part_id": [ "transactional-64afe5f28ffc2-1" ], "number": "420777777778", "channel": "viber" } ] } }

Dabei gilt:

part_ID ist das Array der IDs der Teile der ursprünglichen langen Nachricht, die aufgeteilt wurde, weil sie das Limit von 160 Zeichen für eine einzelne Nachricht überschritten hat. Mehr Informationen hier.

Bei einem Fehler:

{ "type": "invalid_phone_number", "code": 400, "error": "Invalid phone number", "detail": null }

{ "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "detail": null }

Dabei gilt:

type und error (Beschreibung des Fehlers) finden Sie in der Tabelle der Fehlertypen
code steht für den HTTP-Fehler
detail enthält zusätzliche Informationen zum Fehler

Alle Fehlertypen für die Simple API und die Advanced API finden Sie hier.

War diese Seite hilfreich?

KI fragen Kopiert