Resumo
Ao enviar mensagens de modelo usando a API de envio de mensagem de modelo do WATI, é essencial rastrear seu status - enviado, entregue, lido, respondido ou falhou. Isso garante melhor visibilidade e gerenciamento das interações com os clientes.
Instruções
Enviando uma Mensagem de Modelo
Para enviar uma mensagem de modelo usando a API do WATI, utilize o endpoint sendTemplateMessage V2.
Exemplo de Requisição cURL
curl --location 'https://live-server-123.wati.io/api/v2/sendTemplateMessage?whatsappNumber=<whatsappNumber>' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
"template_name": "update_for_you",
"broadcast_name": "JPTestBroadcast",
"parameters": []
}'Exemplo de Resposta da API
{
"result": true,
"error": null,
"templateName": "update_for_you",
"receivers": [
{
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"waId": "<whatsappNumber>",
"isValidWhatsAppNumber": true,
"errors": []
}
],
"parameters": []
}Campo chave:
localMessageId– Um identificador único para rastrear o status da mensagem por meio de webhooks.
Webhooks para Rastreamento do Status da Mensagem
1. Mensagem de Modelo Enviada
Disparado quando: Uma mensagem de modelo é enviada com sucesso.
Evento de Webhook:
templateMessageSent_v2Campo chave:
localMessageIdString de status:
"SENT"
Exemplo de Payload de Webhook
{
"eventType": "templateMessageSent_v2",
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"id": "640c8fd48b67615f886237b8",
"whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
"templateId": "63766ae83b2e064905789c63",
"templateName": "update_for_you",
"created": "2023-03-11T14:27:32.9655388Z",
"statusString": "SENT",
"sourceType": "API"
}2. Mensagem Entregue
Disparado quando: A mensagem é entregue com sucesso ao destinatário.
Evento de Webhook:
sentMessageDELIVERED_v2String de status:
"Delivered"
Exemplo de Payload de Webhook
{
"eventType": "sentMessageDELIVERED_v2",
"statusString": "Delivered",
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"id": "640c8fd48b67615f886237b8",
"whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
"timestamp": "1678544854",
"operatorEmail": "[email protected]"
}3. Mensagem Lida
Disparado quando: O destinatário lê a mensagem.
Evento de Webhook:
sentMessageREAD_v2String de status:
"Read"
Exemplo de Payload de Webhook
{
"eventType": "sentMessageREAD_v2",
"statusString": "Read",
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"id": "640c8fd48b67615f886237b8",
"whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
"timestamp": "1678545043",
"operatorEmail": "[email protected]"
}4. Mensagem Respondida
Disparado quando: O destinatário responde à mensagem.
Evento de Webhook:
sentMessageREPLIED_v2String de status:
"Replied"
Exemplo de Payload de Webhook
{
"eventType": "sentMessageREPLIED_v2",
"statusString": "Replied",
"localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
"id": "640c8fd48b67615f886237b8",
"whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
"timestamp": "1678545074",
"operatorEmail": "[email protected]"
}5. Mensagem Recebida
Disparado quando: Um usuário envia uma mensagem para o seu número do WATI.
Evento de Webhook:
messageReceivedCaso de uso: Pode ser utilizado com Template Message Sent para rastrear cliques em botões de resposta rápida.
Exemplo de Payload de Webhook
{
"eventType": "messageReceived",
"statusString": "Received",
"localMessageId": "fd29c1f-9033-59b2-7d72-5ac964c4c8a7",
"whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
"text": "Hello, I need help!",
"timestamp": "1665645642",
"operatorEmail": "[email protected]"
}
6. Mensagem de Modelo Falhou
Disparado quando: A mensagem de modelo falha ao ser enviada.
Evento de Webhook:
templateMessageFailedDetalhes da falha: Inclui um código de falha e uma mensagem de erro.
Exemplo de Payload de Webhook
{
"eventType": "templateMessageFailed",
"statusString": "Failed",
"localMessageId": "fd29c1f-9033-59b2-7d72-5ac964c4c8a7",
"failedCode": "131026",
"failedDetail": "Mensagem não entregável",
"id": "66b2531d4931581381944612",
"whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
"timestamp": "1665645642",
"operatorEmail": "[email protected]"
}
Como Configurar Webhooks
Acesse o Painel do WATI
Navegue até Webhooks
Clique em "Adicionar Webhook"
Insira sua URL do webhook
Defina o Status como "Habilitado"
Selecione os eventos necessários (ex.: Template Message Sent, Entregue, Lido, etc.)
Seguindo esses passos, você pode rastrear e gerenciar todas as mensagens de modelo enviadas através da API do WATI.
Perguntas Frequentes (FAQs)
Envio de Mensagens de Modelo
1. Como enviar uma mensagem de modelo usando a API do WATI?
→ Para enviar uma mensagem de modelo, utilize o endpoint sendTemplateMessage V2. Você precisa incluir o número do WhatsApp, o nome do modelo e o token de autorização na requisição. Consulte o exemplo de requisição cURL na documentação para obtenção de detalhes.
2. Quais parâmetros eu preciso incluir na requisição da API?
→ Os parâmetros obrigatórios incluem whatsappNumber, template_name, broadcast_name e parameters (se aplicável). Certifique-se de fornecer um token de autorização válido.
Rastreamento do Status da Mensagem
3. Como posso rastrear o status de uma mensagem enviada?
→ Cada resposta da API inclui um localMessageId, que pode ser utilizado para rastrear o status da mensagem por meio de webhooks. Webhooks fornecem atualizações em tempo real para mensagens enviadas, entregues, lidas, respondidas e falhas.
4. Qual evento de webhook rastreia quando uma mensagem é enviada?
→ O evento de webhook templateMessageSent_v2 rastreia quando uma mensagem é enviada. Ele contém o localMessageId, whatsappMessageId e outros metadados.
5. Como saber quando uma mensagem é entregue?
→ O evento de webhook sentMessageDELIVERED_v2 indica que a mensagem foi entregue. O campo statusString terá o valor Delivered.
6. Como rastrear quando uma mensagem é lida?
→ O evento de webhook sentMessageREAD_v2 é acionado quando o destinatário lê a mensagem. O campo statusString terá o valor Read.
7. Posso rastrear se um usuário responde a uma mensagem?
→ Sim, o evento de webhook sentMessageREPLIED_v2 é acionado quando o destinatário responde à mensagem.
Tratamento de Falhas
8. O que acontece se uma mensagem de modelo falhar ao ser enviada?
→ Se uma mensagem falhar, o evento de webhook templateMessageFailed será acionado. Ele fornece um failedCode e failedDetail explicando o motivo da falha.
9. Onde posso encontrar detalhes sobre os códigos de falha?
→ Os códigos de falha são inclusos na carga útil do webhook templateMessageFailed. Você pode consulta a documentação do Meta para uma explicação detalhada de cada código de erro.
Configuração de Webhooks
10. Como habilito webhooks no WATI?
→ Para habilitar webhooks:
Acesse o Painel do WATI.
Navegue até
Webhooks.Clique em
Adicionar Webhook.Insira sua URL do webhook.
Defina o status como
Enabled.Selecione os eventos de webhook que deseja rastrear.
11. Quais eventos de webhook devem ser habilitados para rastreamento completo da mensagem?
→ Para rastrear todo o ciclo de vida da mensagem, habilite os seguintes eventos:
templateMessageSent_v2sentMessageDELIVERED_v2sentMessageREAD_v2sentMessageREPLIED_v2messageReceivedtemplateMessageFailed