## API-URL URL zum Senden von HTTP-Anfragen: ```url https://portal.bulkgate.com/api/1.0/integration/promotional ``` > [!NOTE] > Wenn die Anfrage ihr Ziel nicht erreicht, wiederholen Sie sie auf dem [Backup-Server](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/backup-server/) `backup1.bulkgate.com`. ```http POST /api/1.0/integration/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` ### Parametertabelle | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:------------------|:--------------------------------------------------------|:---------:|:---------------------------------:| | application_id | [Application ID](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-verwaltung/) | **Ja** | - | | application_token | [Authentifizierungstoken der Anwendung](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-tokens/) | **Ja** | - | | tag | Persönliche Kennzeichnung | Nein | - | | messages | Array der Nachrichten | **Ja** | [Nachrichtenobjekt](#nachrichtenobjekt) | ### Nachrichtenobjekt | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:----------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:---------------------------------------:| | primary_channel | Primärer Kanal, der in der Kaskade als erster verwendet wird | Nein | `sms` | | phone_number | Telefonnummer des Empfängers | **Ja** | - | | country | Geben Sie die Nummern der Empfänger im internationalen Format an (mit Vorwahl, z. B. `420`) oder ergänzen Sie den [Ländercode](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`775123456` + `CZ` = `420775123456`). Siehe das Beispiel mit Angabe des Landes. 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](https://en.wikipedia.org/wiki/Unix_time). Siehe die Beispiele unten | Nein | `null` | | channels | Assoziatives Array der Kanalobjekte | **Ja** | [Kanalobjekt](#viber-kanalobjekt) | ### 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 Bildes in der Nachricht | Nein | `null` | | image_zoom | Lässt sich das Bild vergrößern? | Nein | `false` | | text | Text der Nachricht. In die Vorlage können Variablen aus dem Array `variables` (weiterer Parameter) eingefügt werden: `Hallo ....` | **Ja** | - | | variables | Assoziatives Array zum Einfügen von Variablen in den Text, z. B. `{"first_name": "Max", "last_name": "Mustermann"}` | Nein | `[]` | ### SMS-Kanalobjekt | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:----------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:-------------:| | sender_id | Absenderkennung, siehe [Absendertyp](#absendertyp-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 | `''` | | 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` (weiterer Parameter) eingefügt werden: `Hallo ....` | **Ja** | - | | variables | Assoziatives Array zum Einfügen von Variablen in den Text, z. B.: `{"first_name": "Max", "last_name": "Mustermann"}` | Nein | `[]` | #### Absendertyp `sender_id` | WERT | BESCHREIBUNG | |:-----------|:----------------------------------------------------------------------| | `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 Ihre Mobile-Connect-App | | `gOwn` | Eigene Nummer (Verifizierung der Nummer erforderlich) | | `gProfile` | [ID des Absenderprofils](https://www.bulkgate.com/de/hilfe-center/sms/absenderprofil/) | | `` | ID des Absenderprofils | **Beispiel einer vollständigen Anfrage:** ```http-json POST /api/1.0/integration/promotional 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", "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "button_caption": "OK", "button_url": "#", "image": "", "image_zoom": false, "text": "test ", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test ", "variables": { "variable_1": "name" } } } }, { "primary_channel": "sms", "phone_number": "420777777778", "country": "cz", "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "button_caption": "OK", "button_url": "#", "image": "", "image_zoom": false, "text": "test ", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test ", "variables": { "variable_1": "name" } } } } ] } ``` ## Mögliche Antworten auf diese Anfrage: **Im Erfolgsfall** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 2, "scheduled": 0, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [ { "status": "accepted", "message_id": "############-0", "part_id": [ "############-0" ], "number": "420777777777", "channel": "sms" }, { "status": "accepted", "message_id": "############-1", "part_id": [ "############-1" ], "number": "420777777778", "channel": "sms" } ] } } ``` **Im Fehlerfall:** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 0, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [] } } ``` ```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** steht für den HTTP-Fehlercode - **detail** enthält zusätzliche Informationen zum Fehler Alle Fehlertypen für Simple API und Advanced API finden Sie [hier](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-fehlertypen/).