## WhatsApp-Objekt | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:---------------|:-------------------------------------------------------------------------------------------------------------------------------------------|:------------:|:-------------:| | sender | Textabsender. Er muss zuerst registriert werden. Für die Registrierung wenden Sie sich [hier](https://www.bulkgate.com/de/kontaktieren-sie-uns/) an den Support. | **Ja** | - | | expiration | Zeitlimit in Sekunden, nach dessen Ablauf der alternative Kanal verwendet wird. Werte unter `60` werden ignoriert und durch den Standardwert ersetzt | Nein | `180` | | template | Vorlagenobjekt. Kann nicht zusammen mit folgenden Parametern verwendet werden (Message, File, Otp, Location), siehe [Vorlagenobjekt](#vorlagenobjekt) | Nein | `null` | | message | Nachrichtenobjekt. Kann nicht zusammen mit folgenden Parametern verwendet werden (Template, File, Otp, Location), siehe [Nachrichtenobjekt](#nachrichtenobjekt) | Nein | `null` | | file | Dateiobjekt. Kann nicht zusammen mit folgenden Parametern verwendet werden (Template, Message, Otp, Location), siehe [Dateiobjekt](#dateiobjekt) | Nein | `null` | | otp | OTP-Objekt. Kann nicht zusammen mit folgenden Parametern verwendet werden (Template, Message, File, Location), siehe [OTP-Objekt](#otp-objekt) | Nein | `null` | | location | Standortobjekt. Kann nicht zusammen mit folgenden Parametern verwendet werden (Template, Message, File, Otp), siehe [Standortobjekt](#standortobjekt) | Nein | `null` | ## Vorlagenobjekt | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:---------------|:----------------------------------------------------------------------------------------|:------------:|:-------------:| | template | Name der Vorlage | **Ja** | - | | language | Sprache im ISO-Format | **Ja** | - | | header | Header-Objekt der Vorlage, siehe [Header-Objekt](#header-objekt-der-vorlage) | Nein | `null` | | body | Body-Objekt der Vorlage, siehe [Body-Objekt](#body-objekt-der-vorlage) | Nein | `null` | | buttons | Array der Schaltflächenobjekte der Vorlage, siehe [Buttons-Objekt](#buttons-objekt-der-vorlage) | Nein | `null` | ### Header-Objekt der Vorlage | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:---------------|:-----------------------------------------------------------------------------------------------|:---------------------------------------------------------------------:|:-------------:| | type | Typ des Headers (`image`, `video`, `text`, `location`) | **Ja** | - | | url | Pfad zum Video oder Bild (verwendet beim Typ `image`, `video`) | **Ja**, nicht zusammen mit folgenden (`text`, `location`) | - | | caption | Bildunterschrift des Bildes oder Videos (verwendet beim Typ `image`, `video`) | **Ja**, nicht zusammen mit folgenden (`text`, `location`) | - | | text | Text (verwendet beim Typ `text`) | **Ja**, nicht zusammen mit folgenden (`url`, `caption`, `location`) | - | | location | Standortobjekt (verwendet beim Typ `location`), siehe [Standortobjekt](#standortobjekt) | **Ja**, nicht zusammen mit folgenden (`url`, `text`, `caption`) | - | ### Body-Objekt der Vorlage | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:---------------|:---------------------------------------------|:-------------------------------------------------------------:|:-------------:| | type | Typ des Bodys (`text`, `price`, `currency`) | Nein | `text` | | text | Text (verwendet beim Typ `text`) | **Ja**, nicht zusammen mit folgenden (`amount`, `currency`) | - | | amount | Betrag in der festgelegten Währung | **Ja**, nicht zusammen mit folgendem (`text`) | - | | currency | Währung | **Ja**, nicht zusammen mit folgendem (`text`) | - | ### Buttons-Objekt der Vorlage | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:---------------|:----------------------------------------------|:------------------------------------:|:-------------:| | type | Typ der Schaltfläche (`payload`, `url`) | **Ja** | - | | index | Index der definierten Schaltfläche | **Ja** | - | | payload | Metadaten, die nach dem Klick auf die Schaltfläche gesendet werden | **Ja**, nur beim Typ `payload` | - | | text | URL, auf die der Empfänger weitergeleitet wird | **Ja**, nur beim Typ `url` | - | **Beispielanfrage mit Vorlagenobjekt:** ```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": [ "420777777777" ], "channel": { "whatsapp": { "sender": "420777777777", "template": { "template": "order_shipped", "language": "en", "header": { "type": "image", "url": "https://example.com/order-header.jpg", "caption": "Order 4517" }, "body": [ { "type": "text", "text": "John" }, { "type": "currency", "amount": 20.5, "currency": "EUR" } ], "buttons": [ { "type": "url", "index": 1, "text": "4517" } ] } } } } ``` ### Beispiel eines Vorlagenobjekts ![Beispiel eines Vorlagenobjekts](docs:advanced-whatsapp/whatsapp_template_example) ## Nachrichtenobjekt | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:---------------|:------------------------------------|:---------:|:-------------:| | text | Text der Nachricht | **Ja** | - | | preview_url | Vorschau der gesendeten URL als Miniaturbild | Nein | `true` | **Beispiel eines Nachrichtenobjekts:** ```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": [ "420777777777" ], "channel": { "whatsapp": { "sender": "420777777777", "message": { "text": "Your order 4517 has been shipped. Track it at https://example.com/track/4517", "preview_url": true } } } } ``` ## Dateiobjekt | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:---------------|:-----------------------------------------------------------------|:---------:|:-------------:| | type | Typ der Datei (`image`, `video`, `audio`, `document`, `sticker`) | Nein | `image` | | url | Pfad zur Datei | **Ja** | - | | caption | Beschriftung der gesendeten Datei | Nein | "" | **Beispiel eines Dateiobjekts:** ```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": [ "420777777777" ], "channel": { "whatsapp": { "sender": "420777777777", "file": { "type": "document", "url": "https://example.com/invoice-4517.pdf", "caption": "Invoice for order 4517" } } } } ``` ### Beispiel eines Dateiobjekts ![Beispiel eines Dateiobjekts](docs:advanced-whatsapp/whatsapp_file_example) ## OTP-Objekt | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:---------------|:--------------------------------------------------------------------------------------------------------------------|:---------:|:-------------:| | template | Vorlage der Textnachricht, die mit dem Code gesendet wird | **Ja** | - | | code | Einmalcode | **Ja** | - | | language | Sprache, in der die Nachricht mit dem Code gesendet wird (bei `null` wird die Sprache anhand der Telefonnummer ermittelt) | **Ja** | - | **Beispiel eines OTP-Objekts:** ```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": [ "420777777777" ], "channel": { "whatsapp": { "sender": "420777777777", "otp": { "template": "verification_code", "language": "en", "code": "0451" } } } } ``` ## Standortobjekt | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:----------------|:------------------------------------|:---------:|:-------------:| | latitude | Breitengrad als Gleitkommazahl | Nein | - | | longitude | Längengrad als Gleitkommazahl | Nein | - | | name | Name des gesendeten Standorts | Nein | - | | address | Adresse des gesendeten Standorts | Nein | - | **Beispielanfrage mit Standortobjekt:** ```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": [ "420777777777" ], "channel": { "whatsapp": { "sender": "420777777777", "location": { "latitude": 50.086584, "longitude": 14.410763, "name": "Pick-up point", "address": "Karluv most, Praha" } } } } ``` ### Beispiel eines Standortobjekts ![Beispiel eines Standortobjekts](docs:advanced-whatsapp/whatsapp_location_example) ## Beispiel einer vollständigen Anfrage Eine genehmigte Vorlage mit Header, Body-Parametern und einer URL-Schaltfläche, SMS als Ausweichkanal. Die WhatsApp-Stufe ignoriert den `text` der obersten Ebene, der für die SMS-Stufe bestimmt ist. ```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": ["420777777777"], "text": "Your order 4517 has been shipped.", "channel": { "whatsapp": { "sender": "420777777777", "expiration": 300, "template": { "template": "order_shipped", "language": "en", "header": { "type": "image", "url": "https://example.com/order-header.jpg", "caption": "Order 4517" }, "body": [ {"type": "text", "text": "John"}, {"type": "currency", "amount": 20.5, "currency": "EUR"} ], "buttons": [ {"type": "url", "index": 1, "text": "4517"} ] } }, "sms": { "sender_id": "gText", "sender_id_value": "BulkGate" } } } ``` Dieselbe Nachricht als freier Text. Diese ist nur innerhalb des 24-stündigen Servicefensters möglich; außerhalb davon ist eine Vorlage erforderlich. ```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": ["420777777777"], "text": "Your order 4517 has been shipped.", "channel": { "whatsapp": { "sender": "420777777777", "message": { "text": "Your order 4517 has been shipped. Track it at https://example.com/track/4517", "preview_url": true } }, "sms": { "sender_id": "gText", "sender_id_value": "BulkGate" } } } ``` Die Antwort ist für alle Kanäle gleich - siehe [Advanced transactional](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-transactional/2.0/).