## Objeto WhatsApp | NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO | |:---------------|:-------------------------------------------------------------------------------------------------------------------------------------------|:------------:|:-------------:| | sender | Remetente de texto. Tem de ser registado primeiro. Para o registo, contacte o suporte [aqui](https://www.bulkgate.com/pt/contacto/). | **Sim** | - | | expiration | Limite de tempo em segundos após o qual é utilizado o canal alternativo. Os valores inferiores a `60` são ignorados e substituídos pelo valor predefinido | Não | `180` | | template | Objeto template. Não pode ser utilizado em conjunto com os seguintes parâmetros (Message, File, Otp, Location), consulte [Objeto Template](#objeto-template) | Não | `null` | | message | Objeto message. Não pode ser utilizado em conjunto com os seguintes parâmetros (Template, File, Otp, Location), consulte [Objeto Message](#objeto-message) | Não | `null` | | file | Objeto file. Não pode ser utilizado em conjunto com os seguintes parâmetros (Template, Message, Otp, Location), consulte [Objeto File](#objeto-file) | Não | `null` | | otp | Objeto otp. Não pode ser utilizado em conjunto com os seguintes parâmetros (Template, Message, File, Location), consulte [Objeto Otp](#objeto-otp) | Não | `null` | | location | Objeto location. Não pode ser utilizado em conjunto com os seguintes parâmetros (Template, Message, File, Otp), consulte [Objeto Location](#objeto-location) | Não | `null` | ## Objeto Template | NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO | |:---------------|:----------------------------------------------------------------------------------------|:------------:|:-------------:| | template | Nome do template | **Sim** | - | | language | Idioma em formato ISO | **Sim** | - | | header | Objeto de cabeçalho do template, consulte [Objeto de cabeçalho](#objeto-de-cabecalho-do-template) | Não | `null` | | body | Objeto de corpo do template, consulte [Objeto de corpo](#objeto-de-corpo-do-template) | Não | `null` | | buttons | Array de objetos de botões do template, consulte [Objeto de botões](#objeto-de-botoes-do-template) | Não | `null` | ### Objeto de cabeçalho do template | NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO | |:---------------|:-----------------------------------------------------------------------------------------------|:---------------------------------------------------------------------:|:-------------:| | type | Tipo de cabeçalho (`image`, `video`, `text`, `location`) | **Sim** | - | | url | Caminho para o vídeo ou a imagem (utilizado com o tipo `image`, `video`) | **Sim**, não em conjunto com os seguintes (`text`, `location`) | - | | caption | Legenda da imagem ou do vídeo (utilizado com o tipo `image`, `video`) | **Sim**, não em conjunto com os seguintes (`text`, `location`) | - | | text | Texto (utilizado com o tipo `text`) | **Sim**, não em conjunto com os seguintes (`url`, `caption`, `location`) | - | | location | Objeto location (utilizado com o tipo `location`), consulte [Objeto Location](#objeto-location) | **Sim**, não em conjunto com os seguintes (`url`, `text`, `caption`) | - | ### Objeto de corpo do template | NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO | |:---------------|:---------------------------------------------|:-------------------------------------------------------------:|:-------------:| | type | Tipo de corpo (`text`, `price`, `currency`) | Não | `text` | | text | Texto (utilizado com o tipo `text`) | **Sim**, não em conjunto com os seguintes (`amount`, `currency`) | - | | amount | Montante na moeda definida | **Sim**, não em conjunto com os seguintes (`text`) | - | | currency | Moeda | **Sim**, não em conjunto com os seguintes (`text`) | - | ### Objeto de botões do template | NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO | |:---------------|:----------------------------------------------|:------------------------------------:|:-------------:| | type | Tipo de botão (`payload`, `url`) | **Sim** | - | | index | Índice do botão definido | **Sim** | - | | payload | Metadados enviados após clicar no botão | **Sim**, apenas com o tipo `payload` | - | | text | URL para o qual o destinatário será redirecionado | **Sim**, apenas com o tipo `url` | - | **Exemplo de pedido com o objeto template:** ```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" } ] } } } } ``` ### Exemplo de objeto Template ![Exemplo de objeto Template](docs:advanced-whatsapp/whatsapp_template_example) ## Objeto Message | NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO | |:---------------|:------------------------------------|:---------:|:-------------:| | text | Texto da mensagem | **Sim** | - | | preview_url | Pré-visualização do URL enviado como miniatura | Não | `true` | **Exemplo de objeto message:** ```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 } } } } ``` ## Objeto File | NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO | |:---------------|:-----------------------------------------------------------------|:---------:|:-------------:| | type | Tipo de ficheiro (`image`, `video`, `audio`, `document`, `sticker`) | Não | `image` | | url | Caminho para o ficheiro | **Sim** | - | | caption | Legenda do ficheiro enviado | Não | "" | **Exemplo de objeto file:** ```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" } } } } ``` ### Exemplo de objeto File ![Exemplo de objeto File](docs:advanced-whatsapp/whatsapp_file_example) ## Objeto Otp | NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO | |:---------------|:--------------------------------------------------------------------------------------------------------------------|:---------:|:-------------:| | template | Modelo da mensagem de texto enviada com o código | **Sim** | - | | code | Código de utilização única | **Sim** | - | | language | Idioma utilizado para enviar a mensagem com o código (se for utilizado `null`, o idioma é detetado a partir do número de telefone) | **Sim** | - | **Exemplo de objeto otp:** ```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" } } } } ``` ## Objeto Location | NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO | |:----------------|:------------------------------------|:---------:|:-------------:| | latitude | Latitude em número de vírgula flutuante | Não | - | | longitude | Longitude em número de vírgula flutuante | Não | - | | name | Nome da localização enviada | Não | - | | address | Morada da localização enviada | Não | - | **Exemplo de pedido com o objeto location:** ```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" } } } } ``` ### Exemplo de objeto Location ![Exemplo de objeto Location](docs:advanced-whatsapp/whatsapp_location_example) ## Exemplo de pedido completo Um template aprovado com cabeçalho, parâmetros do corpo e um botão URL, com SMS como alternativa. A parte WhatsApp ignora o `text` de nível superior, que se destina à parte SMS. ```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" } } } ``` A mesma mensagem como texto livre. Só pode ser utilizada dentro da janela de serviço de 24 horas; fora dela, é necessário um template. ```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" } } } ``` A resposta é igual para todos os canais - consulte [Advanced transactional](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-transactional/2.0/).