API envio mensagem

Criada por Adrier Santos, Modificado em Ter, 28 Mai, 2024 na (o) 10:08 PM por Adrier Santos

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"
}