Transaktionsnachrichten – Spezifikation

API-URL

URL, an die HTTP-Anfragen gesendet werden:

https://portal.bulkgate.com/api/1.0/integration/transactional

Hinweis

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

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

Vorsicht

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

Hinweis

Wenn Sie über die transaktionale Route Massenbenachrichtigungen versenden möchten, wenden Sie sich bitte an unseren Support. Aus triftigem Grund können wir diese Option freischalten.

Warnung

Empfänger, die sich abgemeldet haben, erhalten die Nachricht trotzdem (das Opt-out gilt nur für Werbenachrichten).

Parametertabelle

PARAMETERNAME	WERT	PFLICHT	STANDARDWERT
application_id	Anwendungs-ID	Ja	-
application_token	Authentifizierungstoken der Anwendung	Ja	-
tag	Persönlicher Identifikations-Tag	Nein	-
primary_channel	Der primäre Kanal, der in der Kaskade zuerst verwendet wird	Nein	`sms`
phone_number	Telefonnummer des Empfängers	Ja	-
country	Geben Sie die Empfängernummern im internationalen Format an (mit Vorwahl, z. B. `420`) oder ergänzen Sie den Ländercode (`775123456` + `CZ` = `420775123456`). Beachten Sie das Beispiel für die Anforderungen eines Landes. Ist der Wert `null`, wird zur Ergänzung der Angabe Ihre eingestellte Zeitzone verwendet	Nein	`null`
schedule	Planen Sie Datum und Uhrzeit des Versands als Unix-Zeitstempel. Siehe Beispiele unten.	Nein	`null`
channels	Assoziatives Array von Kanalobjekten	Ja	Kanalobjekt
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	`false`

Viber-Kanalobjekt

PARAMETERNAME	WERT	PFLICHT	STANDARDWERT
sender	Name des Absenders	Nein	-
expiration	Zeit, nach der die Nachricht abläuft	Nein	`3600`
button_caption	Text der Schaltfläche	Nein	`OK`
button_url	URL der Schaltfläche	Nein	`#`
image	URL des in der Nachricht enthaltenen Bildes	Nein	`null`
image_zoom	Kann das Bild vergrößert werden?	Nein	`false`
text	Nachrichtentext. 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	`[]`

SMS-Kanalobjekt

PARAMETERNAME	WERT	PFLICHT	STANDARDWERT
sender_id	Absenderkennung, siehe Absendertyp	Nein	`gSystem`
sender_id_value	Wert des Absenders - `gOwn` (z. B. „420 777 777 777“), `gText` (z. B. „BulkGate“), `gProfile` (z. B. „423“), `gMobile` oder `gPush` (KEY)	Nein	`''`
unicode	`Yes`/`true`/`1` für Unicode-SMS, `no`/`false`/`0` für 7-Bit-SMS	Nein	`false`
text	SMS-Text (max. 612 Zeichen bzw. 268 Zeichen bei aktiviertem Unicode), Kodierung UTF-8. In die Vorlage können Variablen aus dem Array `variables` (zusätzlicher 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	`[]`

Absendertyp `sender_id`

WERT	BESCHREIBUNG
`gSystem`	Systemnummer
`gShort`	Kurzwahlnummer (Short Code)
`gText`	Textabsender
`gMobile`	Mobile Connect
`gPush`	Mobile Connect Push - sendet eine Benachrichtigung an Ihre Mobile-Connect-App
`gOwn`	Eigene Nummer (erfordert eine Verifizierung der Nummer)
`gProfile`	ID des Absenderprofils
`<int>`	ID des Absenderprofils

Beispiel einer vollständigen Anfrage:

POST /api/1.0/integration/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "tag": "", "primary_channel": "sms", "phone_number": "420777777777", "country": "cz", "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "text": "test <variable_1>", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test <variable_1>", "variables": { "variable_1": "name" } } } }

Mögliche Antworten auf diese Anfrage:

Bei Erfolg

{ "data": { "status": "accepted", "message_id": "omni-############", "part_id": [ "omni-##############" ], "number": "420777777777", "channel": "sms" } }

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