Werbe-SMS – Spezifikation (Advanced API 1.0)

API-URL

URL, an die HTTP-Anfragen gesendet werden:

https://portal.bulkgate.com/api/1.0/advanced/promotional

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/1.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json

Parametertabelle

PARAMETERNAME	WERT	PFLICHT	STANDARDWERT
application_id	Anwendungs-ID	Ja	-
application_token	Anwendungstoken	Ja	-
number	Array der Empfänger – Wert number	Ja oder `admins` oder `groups`	-
groups	Array der Gruppennummern im BulkGate-Adressbuch. Mehr Informationen	Ja oder `number` oder `admins`	-
admins	Array der Nummern von BulkGate-Administratoren, die Benachrichtigungen erhalten. Mehr Informationen	Ja oder `number` oder `groups`	-
text	Text der SMS-Nachricht (max. 612 Zeichen bzw. 268 Zeichen bei aktiviertem Unicode), Kodierung UTF-8	Ja, wenn `number` als Array von Nummern angegeben ist oder der Parameter `groups` bzw. `admin` verwendet wird	-
unicode	`Yes`/`true`/`1` für Unicode-SMS, no/false/0 für 7-Bit-SMS	Nein	`false`
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	`null`
country	Geben Sie die Empfängernummern im internationalen Format an (mit Vorwahl, z. B. `44`) oder fügen Sie den Ländercode hinzu (`7820125799` + `GB` = `447820125799`). 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 oder im Format ISO 8601. Siehe Beispiele unten	Nein	Sofort
duplicates_check	Mit `same_text` verhindern Sie, dass doppelte Nachrichten an dieselbe Telefonnummer gesendet werden. Mit `same_number` unterbinden Sie das Senden einer Nachricht mit gleichem oder anderem Text an dieselbe Nummer. Bei `null` werden keine Duplikate entfernt. Duplikate werden nur innerhalb eines einzelnen Batches entfernt, nicht über mehrere Anfragen hinweg.	Nein	`null`
tag	Label der Nachricht, über das Sie sie später wiederfinden.	Nein	-

Wert `number`

Der Wert number kann auf zwei Arten angegeben werden:

Array von Telefonnummern

[ "447820125799", "447820100234", "420606123456" ]

Assoziatives Array mit dem Schema number, text und variables, wobei nur der Parameter number Pflicht ist. Ist number nicht ausgefüllt, wird die Nachricht übersprungen.

[ {"number": "447820125799", "text": "test1 <a>", "variables": {"a": 5}}, {"number": "447820100234", "text": "test2 <a>", "variables": {"b": 5}}, {"number": "420606123456", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}} ]

Variablen aus dem Array variables können Sie in die Vorlage des Parameters text einfügen.

Typ der Absenderkennung `sender_id`

WERT	BEDEUTUNG
`gSystem`	Systemnummer
`gShort`	Short Code
`gText`	Textabsender
`gMobile`	Mobile Connect
`gPush`	Mobile Connect Push – sendet eine Benachrichtigung an die App Mobile Connect
`gOwn`	Eigene Nummer (erfordert eine Verifizierung der Nummer)
`gProfile`	BulkGate-Profil-ID
`<int>`	BulkGate-Profil-ID

Anfragebeispiele

Beispiel einer vollständigen Anfrage:

POST /api/1.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": [ {"number": "447820125799", "text": "test1 <a>", "variables": {"a": 5}}, {"number": "447820100234", "text": "test2 <a>", "variables": {"b": 5}}, {"number": "420606123456", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}} ], "unicode": true, "groups": [1, 2], "admins": [1, 4], "text": "Hello, <first_name> <last_name>", "sender_id": "gText", "sender_id_value": "BulkGate", "country": "cz", "schedule": "2018-05-14T18:30:00-01:00" }

Beispiel einer Anfrage, bei der die Empfänger als Array von Nummern angegeben werden und die Zeit als Unix-Zeitstempel geplant wird:

POST /api/1.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": [ "420775123456", "420606123456", "44771447678" ], "text": "Hello, <first_name> <last_name>", "schedule": "1526992636" }

Antwort

Bei Erfolg:

{ "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 1, "invalid_sender": 0 } }, "response": [ { "status": "scheduled", "sms_id": "idyrcmdd-0", "part_id": [ "idyrcmdd-0_1", "idyrcmdd-0" ], "number": "420775123456", "channel": "sms" }, { "status": "scheduled", "sms_id": "idyrcmdd-1", "part_id": [ "idyrcmdd-1_1", "idyrcmdd-1" ], "number": "420606123456", "channel": "sms" }, { "status": "invalid_number", "code": 400, "error": "Invalid phone number", "detail": null, "number": "44771447678", "channel": "sms" } ] } }

Dabei gilt:

part_ID ist das Array der IDs der Teile einer ursprünglich langen Nachricht, die aufgeteilt wurde, weil sie das Limit von 160 Zeichen für eine einzelne Nachricht überschritt. 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 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