> [!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 zur Benachrichtigung verwendet werden – als SMS-Benachrichtigung. > [!NOTE] > Möchten Sie eine Massenbenachrichtigung über die transaktionale Route versenden, wenden Sie sich bitte an [unseren Support](https://www.bulkgate.com/de/kontaktieren-sie-uns/). Aus triftigem Grund können wir diese Möglichkeit freischalten. ## API-URL URL zum Senden der HTTP-Anfragen: ```url https://portal.bulkgate.com/api/2.0/advanced/transactional ``` > [!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/2.0/advanced/transactional 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 | [Authentifizierungstoken der Anwendung](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-tokens/) | **Ja** | - | | number | Nummer des Empfängers oder Array von Empfängernummern – [Wert number](#wert-number) | **Ja** oder `admin` | - | | admin | Nummer des BulkGate-Administrators, der die Benachrichtigung erhält. [Mehr Informationen](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-transactional-benachrichtigungen-an-administratoren/) | **Ja** oder `number` | - | | text | Text der SMS-Nachricht (max. 612 Zeichen bzw. 268 Zeichen bei Verwendung von Unicode), UTF-8-Kodierung. 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 | `[]` | | channel | Alternative Kanäle. Die Kanäle werden in einer Kaskade durchlaufen, und zwar in der Reihenfolge, in der Sie sie im Objekt aufführen – können wir Ihre Nachricht über den ersten Kanal nicht zustellen, wird der nächste in der Liste verwendet. SMS wird **nicht** automatisch angehängt; möchten Sie sie als letzte Ausweichoption nutzen, nehmen Sie das Objekt `sms` in die Kaskade auf. Ist gar kein Kanal angegeben, wird die Nachricht als SMS versendet. | Nein | [SMS-Objekt](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-sms/) | | country | Geben Sie die Empfängernummern im internationalen Format an (mit Vorwahl, z. B. `420`) oder fügen Sie den [Ländercode im Format ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) hinzu (`777777777` + `CZ` = `420777777777`). Siehe die Beispielanfrage mit Land. 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) oder im Format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). | Nein | Sofort | | 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 | `off` | | tag | Kennzeichnung der Nachricht, über die der Benutzer sie später wiederfinden kann. | Nein | - | ### Wert `number` Der Wert number kann wie folgt angegeben werden: - Array von Telefonnummern ```json [ "420777777777", "420888888888", "420999999999" ] ``` ## Kanäle Das Objekt `channel` legt fest, über welche Kanäle und in welcher Reihenfolge die Nachricht versendet wird. **Die Reihenfolge der Schlüssel in Ihrer Anfrage ist die Reihenfolge der Kaskade**, und SMS wird nicht automatisch angehängt – siehe [Kanalkaskade](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-kaskade/). | SCHLÜSSEL | KANALOBJEKT | |:-------------|:---------------------------------------------------------------| | `sms` | [SMS](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-sms/) | | `viber` | [Viber – transaktional](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-viber-transaktional/) | | `rcs` | [RCS](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-rcs/) | | `whatsapp` | [WhatsApp](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-whatsapp/) | ## Beispielanfrage ```http-json POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": ["777777777", "777777778"], "text": "Beispieltext ", "variables": {"first_name": "John"}, "country": "cz", "schedule": "2023-08-14T18:30:00-01:00", "channel": { "whatsapp": { "sender": "420777777777", "expiration": 300, "message": { "text": "text" } }, "rcs": { "sender": "BulkGate", "expiration": 300, "message": { "text": "text" } }, "viber": { "sender": "BulkGate", "expiration": 100 }, "sms": { "sender_id": "gText", "sender_id_value": "Mr. Sender", "unicode": true } } } ``` ## Antwort **Bei Erfolg:** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0, "duplicity_message": 0 } }, "response": [ { "status": "scheduled", "message_id": "transactional-64afe5f28ffc2-0", "part_id": [ "transactional-64afe5f28ffc2-0" ], "number": "420777777777", "channel": "viber" }, { "status": "scheduled", "message_id": "transactional-64afe5f28ffc2-1", "part_id": [ "transactional-64afe5f28ffc2-1" ], "number": "420777777778", "channel": "viber" } ] } } ``` Dabei gilt: - **part_ID** ist das Array der IDs der Teile der ursprünglichen langen Nachricht, die aufgeteilt wurde, weil sie das Limit von 160 Zeichen für eine einzelne Nachricht überschritten hat. 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** 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/).