API envio mensagem
Api de envio de mensagem para whatsapp (send-template)
Como enviar uma mensagem
Para que seja possível enviar uma mensagem para o cliente final, é necessário passar por duas etapas:
- Precisa ser cadastrado um template (esse template pode ser utilizado mais de uma vez)
- Envio da mensagem utilizando esses templates
A utilização dos templates são obrigatórias pois existe algumas definições da API da Meta e isso também irá garantir que uma sessão seja aberta caso não exista nenhuma disponível.
Criação do Template
Os templates servem de forma para o envio das mensages. Podemos ter templates com e sem variáveis.
URL
POST <https://api.newtail.com.br/messaging-campaign/template>
Autenticação
Veja mais em: Como se autenticar
Body
Campo | Descrição | Tipo | Obrigatório |
---|---|---|---|
title | Título do template | String | Obrigatório |
description | Descrição do template | String | |
messages | Mensagens e configuração da mensagem | Array | Obrigatório |
messages[].text | Mensagem que vai ser enviada pro cliente final | String | Obrigatório |
media | Anexo da mensagem (pdf, video, imagem) | Object | Opcional |
media.type | Tipo da midia ('image', 'video', 'document’) | String (ENUM) | Obrigatório |
media.url | Link direto do anexo | String | Obrigatório |
media.name | Nome do anexo | String | Obrigatório |
Como criar uma template com texto simples:
Para o envio de mensagens com texto simples, basta escrever o texto que deseja enviar, podendo colocar quebra de linha, acentuação e emojis.
{
"title": "Festival de frutas",
"description": "Evento das frutas",
"messages": [
{
"text": "Olá carioca de coração!! ❤️\\n\\nNosso festival de frutas da estação começou com tudo! 🍒🍇🍉😋\\n\\nQuer aproveitar as promoções?",
}
],
"media": {
"type": "document",
"url": "<https://cdn.newtail.com.br/campaign/3236e71db9e07d34727a0006c1392ce5-ta-var-jun-13-06-006-divinopolis.pdf>",
"name": "Campanha frutas"
}
}
Como criar uma template com texto contendo variáveis:
As variáveis em um template, precisam ser definidas em um formato especial entre duas chaves com um número indicado a posição da variáveis, essa posição inicia em 1.
Exemplo:
Olá {{1}}, tudo bem com você?
Exemplo de envio com variáveis
{
"title": "Festival de frutas",
"description": "Evento das frutas",
"messages": [
{
"text": "Olá {{1}}. Tenha um ótimo dia! ❤️❤️❤️❤️",
}
]
}
Exemplo de envio com variáveis e Media
{
"title": "Festival de frutas",
"description": "Evento das frutas",
"messages": [
{
"text": "Olá {{1}}. Tenha um ótimo dia! ❤️❤️❤️❤️",
}
],
"media": {
"type": "document",
"url": "<https://cdn.newtail.com.br/campaign/3236e71db9e07d34727a0006c1392ce5-ta-var-jun-13-06-006-divinopolis.pdf>",
"name": "Campanha frutas"
}
}
Retornos
Em caso de sucesso: 200
{
"account_id": "xxxxxx",
"title": "Festival de frutas",
"description": "Evento das frutas",
"messages": [
{
"text": "Olá {{1}}. Tenha um ótimo dia! ❤️❤️❤️❤️",
}
],
"media": {
"type": "document",
"url": "<https://cdn.newtail.com.br/campaign/3236e71db9e07d34727a0006c1392ce5-ta-var-jun-13-06-006-divinopolis.pdf>",
"name": "Campanha frutas"
},
"status": "in_review",
"active": true,
"external_id": "xxxxx",
"_id": "63063e4b816209cfd63a220b",
"createdAt": "2022-08-24T15:05:47.284Z",
"updatedAt": "2022-08-24T15:05:47.284Z"
}
Erros:
Em caso de erro de validação: 400
{
"messages": ["field required"]
}
Envio da mensagem
⚠️ Antes de enviar a mensagem, o template precisa estar aprovado, caso contrário, não será possível.
Para verificar se o template foi aprovado, fazer uma request para https://api.newtail.com.br/api/messaging-campaign/template/:template_id
e o status do template esperado deve ser approved
.
URL
POST <https://api.newtail.com.br/notification/send-template>
Autenticação
Veja mais em: Como se autenticar
Body
Campo | Descrição | Tipo | Obrigatório | Padrão |
---|---|---|---|---|
customer_number | Número do whatsapp que vai receber a mensagem | |||
formato: 55DDDNUMERO | String | Obrigatório | ||
template_id | Id do template da mensagem | String | Obrigatório | |
show_chat | Decide se a conversa com cliente vai aparecer na tela do atendimento | Boolean | false | |
media | Anexo da mensagem (pdf, video, imagem) | Object | ||
media.type | Tipo da midia ('image', 'video', 'document’) | String (ENUM) | Obrigatório | |
media.url | Link direto do anexo | String | Obrigatório | |
params | Parâmetros da mensagem do template | Array<String> |
Exemplo de envio de Mensagem sem Variável
{
"customer_number": "55xxxxxxxxx",
"template_id": "62a78ea157531979dfa8c06c"
}
Exemplo de Envio de Mensagem com Variável
{
"customer_number": "55xxxxxxxxx",
"template_id": "62a78ea157531979dfa8c06c",
"show_chat": false,
"params": ["Joãozinho"]
}
Exemplo de Envio de Mensagem com Anexo
{
"customer_number": "55xxxxxxxxx",
"template_id": "62a78ea157531979dfa8c06c",
"show_chat": false,
"media": {
"type": "document",
"url": "<https://cdn.newtail.com.br/campaign/3236e71db9e07d34727a0006c1392ce5-ta-var-jun-13-06-006-divinopolis.pdf>"
},
"params": ["Joãozinho"]
}
Retorno
-
Em caso de sucesso: 202
{ "status": "delivered" }
É importante notar que o envio da mensagem é uma promessa de entrega e será processada em background e não haverá mensagem de retorno de sucesso ou callback.
-
Em caso de erro de validação: 400
{ "error": "Failed to validate fields", "messages": ["field required"] }
-
Caso não encontre o template cadastrado ou o template não esteja aprovado: 400
{
"error": "Template is in review"
}
Comentários
0 comentário
Por favor, entre para comentar.