Transaktions-Massennachrichten – Spezifikation

API-URL

URL, an die HTTP-Anfragen gesendet werden:

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

Hinweis

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

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

Vorsicht

Es ist streng verboten, 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 über die transaktionale Route Benachrichtigungen in großen Mengen senden, wenden Sie sich bitte an unseren Support. Aus berechtigten Gründen können wir diese Option freischalten.

Warnung

Auch Empfänger, die sich abgemeldet haben, erhalten die Nachricht (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önliches Identifikationslabel	Nein	-
messages	Array von Nachrichten	Ja	Nachrichtenobjekt

Nachrichtenobjekt

PARAMETERNAME	WERT	PFLICHT	STANDARDWERT
primary_channel	Primärer 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 fügen Sie den Ländercode hinzu (`775123456` + `CZ` = `420775123456`). Siehe das Beispiel zur Länderangabe. Ist der Wert `null`, wird die Angabe anhand der von Ihnen eingestellten Zeitzone ergänzt	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

Viber-Kanalobjekt

PARAMETERNAME	WERT	PFLICHT	STANDARDWERT
sender	Name des Absenders	Nein	-
expiration	Zeit, nach der die Nachricht abläuft	Nein	`3600`
text	Text der Nachricht. 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 Typ der Absenderkennung	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	Text der SMS (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	`[]`

Typ der Absenderkennung `sender_id`

WERT	BESCHREIBUNG
`gSystem`	Systemnummer
`gShort`	Short Code
`gText`	Textabsender
`gMobile`	Mobile Connect
`gPush`	Mobile Connect Push – sendet eine Benachrichtigung an Ihre App Mobile Connect
`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-bulk HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "tag": "", "messages": [ { "primary_channel": "sms", "phone_number": "420777777777", "country": "cz", "schedule": 1683101313, "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" } } } }, { "primary_channel": "sms", "phone_number": "420777777778", "country": "cz", "schedule": 1683101313, "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": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [ { "status": "scheduled", "message_id": "#############-0", "part_id": [ "#############-0" ], "number": "420777777777", "channel": "sms" }, { "status": "scheduled", "message_id": "#############-1", "part_id": [ "#############-1" ], "number": "420777777778", "channel": "sms" } ] } }

Bei einem Fehler:

{ "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 0, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [] } }

{ "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 ist der HTTP-Fehlercode
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