## WhatsApp object | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:---------------|:-------------------------------------------------------------------------------------------------------------------------------------------|:------------:|:-------------:| | sender | Text sender. Needs to be registered first. For registration contact support [here](https://www.bulkgate.com/en/contact-us/). | **Yes** | - | | expiration | Time limit in seconds after which alternative channel will be used. Values below `60` are ignored and replaced by the default | No | `180` | | template | Template object. Cannot be used in tandem with following parameters (Message, File, Otp, Location) see [Template object](#template-object) | No | `null` | | message | Message object. Cannot be used in tandem with following parameters (Template, File, Otp, Location) see [Message object](#message-object) | No | `null` | | file | File object. Cannot be used in tandem with following parameters (Template, Message, Otp, Location) see [File object](#file-object) | No | `null` | | otp | Otp object. Cannot be used in tandem with following parameters (Template, Message, File, Location) see [Otp object](#otp-object) | No | `null` | | location | Location object. Cannot be used in tandem with following parameters (Template, Message, File, Otp) see [Location object](#location-object) | No | `null` | ## Template object | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:---------------|:----------------------------------------------------------------------------------------|:------------:|:-------------:| | template | Template name | **Yes** | - | | language | Language in Iso format | **Yes** | - | | header | Template header object, see [Header object](#template-header-object) | No | `null` | | body | Template body object, see [Body object](#template-body-object) | No | `null` | | buttons | Array of template button objects, see [Buttons object](#template-buttons-object) | No | `null` | ### Template header object | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:---------------|:-----------------------------------------------------------------------------------------------|:---------------------------------------------------------------------:|:-------------:| | type | Type of header (`image`, `video`, `text`, `location`) | **Yes** | - | | url | Path to video, or image (used with `image`, `video` type) | **Yes**, not in tandem with folliwing (`text`, `location`) | - | | caption | Caption of image, or video (used with `image`, `video` type) | **Yes**, not in tandem with folliwing (`text`, `location`) | - | | text | Text (used with `text` type) | **Yes**, not in tandem with folliwing (`url`, `caption`, `location`) | - | | location | Location object (used with `location` type), see [Location object](#location-object) | **Yes**, not in tandem with folliwing (`url`, `text`, `caption`) | - | ### Template body object | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:---------------|:---------------------------------------------|:-------------------------------------------------------------:|:-------------:| | type | Type of body (`text`, `price`, `currency`) | No | `text` | | text | Text (used with `text` type) | **Yes**, not in tandem with folliwing (`amount`, `currency`) | - | | amount | Amount of set currency | **Yes**, not in tandem with folliwing (`text`) | - | | currency | Currency | **Yes**, not in tandem with folliwing (`text`) | - | ### Template buttons object | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:---------------|:----------------------------------------------|:------------------------------------:|:-------------:| | type | Type of button (`payload`, `url`) | **Yes** | - | | index | Index of defined button | **Yes** | - | | payload | Meta data sent after clickling the button | **Yes**, only with `payload` type | - | | text | Url to which recipient will be redirected to | **Yes**, only with `url` type | - | **Example of template object request:** ```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" } ] } } } } ``` ### Example Template object ![File Object](docs:advanced-whatsapp/whatsapp_template_example) ## Message object | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:---------------|:------------------------------------|:---------:|:-------------:| | text | Text of a message | **Yes** | - | | preview_url | Preview sent url as a thumbnail | No | `true` | **Example of message object:** ```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 } } } } ``` ## File object | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:---------------|:-----------------------------------------------------------------|:---------:|:-------------:| | type | Type of file (`image`, `video`, `audio`, `document`, `sticker`) | No | `image` | | url | Path to the file | **Yes** | - | | caption | Caption of sent file | No | "" | **Example of File object:** ```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" } } } } ``` ### Example File object ![File Object](docs:advanced-whatsapp/whatsapp_file_example) ## Otp object | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:---------------|:--------------------------------------------------------------------------------------------------------------------|:---------:|:-------------:| | template | Template of text message being send with the code | **Yes** | - | | code | One time code | **Yes** | - | | language | Language used to send the message containing code (if `null` is used language will be detected from phone number) | **Yes** | - | **Example of Otp object:** ```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" } } } } ``` ## Location object | PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE | |:----------------|:------------------------------------|:---------:|:-------------:| | latitude | Latitude in floating point number | No | - | | longitude | Longitude in floating point number | No | - | | name | Name of sent location | No | - | | address | Address of sent location | No | - | **Example of Location object request:** ```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" } } } } ``` ### Example Location object ![File Object](docs:advanced-whatsapp/whatsapp_location_example) ## Example of full request An approved template with a header, body parameters and a URL button, SMS as the fallback. The WhatsApp leg ignores the top-level `text`, which is there for the SMS leg. ```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" } } } ``` The same message as free text. It can only be used inside the 24 hour service window; outside of it a template is required. ```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" } } } ``` The response is the same for every channel - see [Advanced transactional](https://www.bulkgate.com/en/docs/advanced-api/advanced-transactional/2.0/).