## API-URL URL, an die HTTP-Anfragen gesendet werden: ```url https://portal.bulkgate.com/api/1.0/integration/transactional ``` > [!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/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` > [!CAUTION] > Es ist **strengstens untersagt**, [transaktionale SMS](https://www.bulkgate.com/de/hilfe-center/allgemeine-informationen/unterschied-werbliche-transaktionale-nachrichten/) für Werbe- oder Marketingzwecke zu missbrauchen. Sie dürfen ausschließlich zu Benachrichtigungszwecken verwendet werden – als SMS-Benachrichtigung. > [!NOTE] > Wenn Sie über die transaktionale Route Massenbenachrichtigungen versenden möchten, wenden Sie sich bitte an [unseren Support](https://www.bulkgate.com/de/kontaktieren-sie-uns/). Aus triftigem Grund können wir diese Option freischalten. > [!WARNING] > 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](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ö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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`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.](https://en.wikipedia.org/wiki/Unix_time) Siehe Beispiele unten. | Nein | `null` | | channels | Assoziatives Array von Kanalobjekten | **Ja** | [Kanalobjekt](#viber-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 ....` | **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](#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 | 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 ....` | **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](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 (erfordert eine Verifizierung der Nummer) | | `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/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 ", "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: **Bei Erfolg** ```json { "data": { "status": "accepted", "message_id": "omni-############", "part_id": [ "omni-##############" ], "number": "420777777777", "channel": "sms" } } ``` **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** 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](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-fehlertypen/).