## API-URL URL, an die HTTP-Anfragen gesendet werden: ```url https://portal.bulkgate.com/api/1.0/advanced/promotional ``` > [!NOTE] > Erreicht die Anfrage ihr Ziel nicht, wiederholen Sie sie auf dem [Backup-Server](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/backup-server/) `backup1.bulkgate.com`. ## Unterstützte HTTP-Methoden - `POST` - `application/json` ```http 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](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-verwaltung/) | **Ja** | - | | application_token | [Anwendungstoken](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-tokens/) | **Ja** | - | | number | Array der Empfänger – [Wert number](#wert-number) | **Ja** oder `admins` oder `groups` | - | | groups | Array der Gruppennummern im BulkGate-Adressbuch. [Mehr Informationen](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-promotional-versand-an-gruppen-aus-dem-adressbuch/) | **Ja** oder `number` oder `admins` | - | | admins | Array der Nummern von BulkGate-Administratoren, die Benachrichtigungen erhalten. [Mehr Informationen](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-promotional-nachrichten-an-administratoren/) | **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](#typ-der-absenderkennung-sender-id) | 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)](https://www.bulkgate.com/de/hilfe-center/mobile-connect/mobile-connect-installation/) | Nein | `null` | | country | Geben Sie die Empfängernummern im internationalen Format an (mit Vorwahl, z. B. `44`) oder fügen Sie den [Ländercode](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) 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](https://en.wikipedia.org/wiki/Unix_time) oder im Format [ISO 8601.](https://en.wikipedia.org/wiki/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 ```json [ "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. ```json [ {"number": "447820125799", "text": "test1 ", "variables": {"a": 5}}, {"number": "447820100234", "text": "test2 ", "variables": {"b": 5}}, {"number": "420606123456", "text": "test3 ", "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](https://www.bulkgate.com/de/hilfe-center/mobile-connect/mobile-connect-installation/) | | `gPush` | Mobile Connect Push – sendet eine Benachrichtigung an die App Mobile Connect | | `gOwn` | Eigene Nummer (erfordert eine Verifizierung der Nummer) | | `gProfile` | [BulkGate-Profil-ID](https://www.bulkgate.com/de/hilfe-center/sms/absenderprofil/) | | `` | BulkGate-Profil-ID | ## Anfragebeispiele **Beispiel einer vollständigen Anfrage:** ```http-json 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 ", "variables": {"a": 5}}, {"number": "447820100234", "text": "test2 ", "variables": {"b": 5}}, {"number": "420606123456", "text": "test3 ", "variables": {"c": 3, "d": "abc"}} ], "unicode": true, "groups": [1, 2], "admins": [1, 4], "text": "Hello, ", "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:** ```http-json 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, ", "schedule": "1526992636" } ``` ## Antwort **Bei Erfolg:** ```json { "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](https://www.bulkgate.com/de/hilfe-center/sms/nachrichtenverkettung/). **Bei einem Fehler:** ```json { "type": "invalid_phone_number", "code": 400, "error": "Invalid phone number", "detail": null } ``` ```json { "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](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-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](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-fehlertypen/).