Resumo

Ao enviar mensagens de modelo usando a API do Wati, você pode rastrear seus status — enviado, entregue, lido, respondido ou falha — usando webhooks em tempo real, em vez de depender apenas das análises de campanha integradas do Wati.

Após enviar campanhas via API, você pode visualizar seu desempenho na Visão Geral da Campanha no Wati. Os webhooks permitem que você rastreie o status da mensagem e os eventos de entrega por meio de seus próprios sistemas à medida que ocorrem.

Nota: Para a documentação de referência completa sobre webhooks, consulte a documentação para desenvolvedores do Wati.

Instruções

Enviar uma Mensagem de Modelo

Use o endpoint v3 para enviar uma mensagem de modelo. A versão v3 é recomendada para todas as novas integrações.

Endpoint: POST https://live-mt-server.wati.io/api/ext/v3/messageTemplates/send

Os caminhos da v3 não incluem /{tenantId}/. Crie um token de API com escopo em Connector > API > Create API Token com o escopo messagetemplatev3:write.

Exemplo de requisição cURL:

curl --location 'https://live-mt-server.wati.io/api/ext/v3/messageTemplates/send' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "template_name": "update_for_you",
  "broadcast_name": "JPTestBroadcast",
  "channel_number": "85264318722",
  "target": "<whatsappNumber>",
  "parameters": []
}'

O channel_number é obrigatório. Use dígitos com o código do país, sem o "+" (ex: 85264318722). O target aceita um número de telefone, ContactId, BSUID ou Channel:PhoneNumber.

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": []
}

Importante: Uma resposta 200 significa que a requisição foi aceita, não que a mensagem foi entregue. A entrega é confirmada pelo webhook sentMessageDELIVERED_v2. Falhas são reportadas pelo templateMessageFailed.

Campo chave:

localMessageId — Identificador único da mensagem. Salve este valor — ele vincula todos os eventos de webhook de status de saída à mensagem original.

Rastrear o Status da Mensagem usando Webhooks

Uma vez enviada, o Wati dispara eventos de webhook para cada atualização de status. Use o localMessageId para corresponder os eventos à mensagem original.

1. Mensagem de Modelo Enviada

Disparado quando: A mensagem é aceita e enviada pelo Wati
Evento: templateMessageSent_v2
Status: SENT

SENT significa que a mensagem saiu do sistema do Wati — não que ela foi entregue ao dispositivo do destinatário.

Exemplo de payload:

{
  "eventType": "templateMessageSent_v2",
  "localMessageId": "84689938-5e2-877821d672c2",
  "id": "693fd8ee21f81",
  "whatsappMessageId": "wamid.HBgNODEYEjQ3RDMzQzM2QjM3QjU1ODQ4RQA=",
  "templateId": "6929b",
  "templateName": "test_jm4",
  "created": "2025-12-15T09:46:23.4083984Z",
  "conversationId": "68b68470e93cc",
  "ticketId": "693fd6ab545f82",
  "text": "Make your messages personal using variables like name and get more replies!",
  "operatorEmail": "[email protected]",
  "waId": "86151285",
  "type": "template",
  "statusString": "SENT",
  "sourceType": "WEB",
  "channelId": null,
  "channelPhoneNumber": "174742",
  "bsuid": "HK.xxxxxxxxxxxxx",
  "parentBsuid": "HK.ENT.xxxxxxxxxxxxx",
  "username": "@bob",
  "templateContent": {
    "header": { "type": "text", "text": "Hello" },
    "footer": "Footer text",
    "buttons": [
      { "type": "QUICK_REPLY", "text": "Yes" },
      { "type": "URL", "text": "Visit us", "url": "https://example.com" },
      { "type": "CALL", "text": "Call us", "phoneNumber": "+1234567890" }
    ]
  }
}

Campos de templateContent:

Campo	Descrição
`header`	Tipo e conteúdo do cabeçalho (texto, imagem, vídeo ou documento)
`footer`	Texto do rodapé
`buttons`	Array de botões — tipos `QUICK_REPLY`, `URL` e `CALL`

O webhook de mensagem de modelo enviada agora inclui informações sobre botões

O Webhook de Template Enviado agora inclui informações sobre os botões configurados no modelo do WhatsApp. Isso permite que você identifique o texto do botão associado a uma mensagem de modelo enviada.

Este recurso está disponível para clientes nos planos Pro, Business e Enterprise.

Quais informações de botão estão incluídas?

O payload do webhook pode incluir as seguintes informações de botão do modelo do WhatsApp:

Texto do botão de resposta rápida
Texto do botão de link

Ao recuperar informações de modelo através da API, a resposta também inclui o texto do botão configurado para o modelo.

Variante BSUID

O templateMessageSent_v2_bsuid dispara o mesmo evento com os campos bsuid, parentBsuid e username para identificar contatos por BSUID em vez de número de telefone.

2. Mensagem Entregue

Disparado quando: A mensagem é entregue ao dispositivo do destinatário
Evento: sentMessageDELIVERED_v2
Status: Delivered

Exemplo de payload:

{
  "eventType": "sentMessageDELIVERED_v2",
  "statusString": "Delivered",
  "localMessageId": "16bf77ae-79e8-691eb4b",
  "id": "693fd65f99391640",
  "whatsappMessageId": "wamid.HBgNODYxMzEzMzg4Nzg2MDU0OEM0NTYxRTlBMwA=",
  "conversationId": "68cba32b3349e",
  "ticketId": "693f7a0a8545f54",
  "text": "hello",
  "type": "text",
  "timestamp": "1765791326",
  "assigneeId": "65a105b5cf65262",
  "operatorEmail": "derre.ai",
  "channelId": null,
  "channelPhoneNumber": "17742"
}

Variante BSUID: sentMessageDELIVERED_v2_bsuid

3. Mensagem Lida

Disparado quando: O destinatário lê a mensagem
Evento: sentMessageREAD_v2
Status: Read

Exemplo de payload:

{
  "eventType": "sentMessageREAD_v2",
  "statusString": "Read",
  "localMessageId": "16bf77ae-79e691eb4b",
  "id": "693fd65f961dc81779391640",
  "whatsappMessageId": "wamid.HBgNODYxMzEABEYEjVCNzg2MDU0OEM0NTYxRTlBMwA=",
  "conversationId": "68cba3db12b3349e",
  "ticketId": "693fd64d1d45f54",
  "text": "hello",
  "type": "text",
  "timestamp": "17651326",
  "assigneeId": "65a10905cf65262",
  "operatorEmail": "[email protected]",
  "channelId": null,
  "channelPhoneNumber": "174742"
}

Variante BSUID: sentMessageREAD_v2_bsuid

4. Mensagem Respondida

Disparado quando: O destinatário responde à mensagem
Evento: sentMessageREPLIED_v2
Status: Replied

Exemplo de payload:

{
  "eventType": "sentMessageREPLIED_v2",
  "statusString": "Replied",
  "localMessageId": "16bf77ae-79e691eb4b",
  "id": "693fd65f961dc81779391640",
  "whatsappMessageId": "wamid.HBgNODYxMzEABEYEjVCNzg2MDU0OEM0NTYxRTlBMwA=",
  "conversationId": "68cba3db12b3349e",
  "ticketId": "693fd64d1d45f54",
  "text": "hello",
  "type": "text",
  "timestamp": "17651326",
  "assigneeId": "65a10905cf65262",
  "operatorEmail": "[email protected]",
  "channelId": null,
  "channelPhoneNumber": "174742"
}

Variante BSUID: sentMessageREPLIED_v2_bsuid

5. Mensagem Recebida

Disparado quando: Um usuário envia uma mensagem para o seu número Wati
Evento: message
Status: Received

Casos de uso:

Rastrear mensagens recebidas de usuários
Capturar cliques em botões de resposta rápida de mensagens de modelo
Detectar respostas a uma mensagem de saída específica usando replyContextId

Mensagens recebidas não possuem um localMessageId. Para vincular uma resposta à mensagem de modelo original, use replyContextId — ele contém o whatsappMessageId da mensagem de saída original.

Exemplo de payload — mensagem de texto:

{
  "eventType": "message",
  "statusString": "Received",
  "whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
  "replyContextId": "wamid.HBgNODEYEjQ3RDMzQzM2QjM3QjU1ODQ4RQA=",
  "text": "Hello, I need help!",
  "timestamp": "1665645642",
  "operatorEmail": "[email protected]"
}

Exemplo de payload — clique em botão de resposta rápida:

{
  "eventType": "message",
  "statusString": "Received",
  "whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
  "buttonReply": {
    "id": "btn_yes",
    "title": "Yes"
  },
  "timestamp": "1665645642",
  "operatorEmail": "[email protected]"
}

6. Falha na Mensagem de Modelo

Disparado quando: A mensagem falha ao ser enviada
Evento: templateMessageFailed
Status: Failed

Exemplo de payload:

{
  "eventType": "templateMessageFailed",
  "statusString": "Failed",
  "localMessageId": "fd29c1f-9033-59b2-7d72-5ac964c4c8a7",
  "failedCode": "131026",
  "failedDetail": "Message undeliverable",
  "id": "66b2531d4931581381944612",
  "whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
  "conversationId": "66b1fb044045cedb1f19538e",
  "ticketId": "66bdfba190194752bb7326d7",
  "text": null,
  "type": "template",
  "timestamp": "1665645642",
  "assigneeId": null,
  "operatorEmail": "[email protected]"
}

channelPhoneNumber só é incluído neste payload quando o webhook está vinculado a um número específico.

Como configurar Webhooks no Wati

Via interface do Wati:

Vá para Connector > Webhooks.
Clique em Add Webhook.

Insira a URL do seu webhook e defina o status como Enabled (Ativado).
Selecione os eventos para os quais deseja se inscrever:
- Template Message Sent (Mensagem de Modelo Enviada)
- Delivered (Entregue)
- Read (Lido)
- Replied (Respondido)
- Failed (Falha)

Via API:

Crie um webhook (v2):

POST https://live-mt-server.wati.io/{tenantId}/api/v2/webhookEndpoints

Liste, obtenha, atualize e exclua webhooks (v3 — recomendado):

https://live-mt-server.wati.io/api/ext/v3/webhooks

Os endpoints de webhook da v3 não incluem /{tenantId}/ no caminho.

Notas Finais

Sempre armazene o localMessageId da resposta de envio — ele vincula todos os eventos de status de saída à mensagem original.
Para mensagens de entrada, use replyContextId para vincular uma resposta à mensagem de saída original.
Use buttonReply para detectar interações com botões de resposta rápida.
Combine múltiplos eventos de webhook para construir uma visão completa do ciclo de vida da mensagem.

Como rastrear a entrega de mensagens de modelo e o status da mensagem usando webhooks do Wati

Resumo

Instruções

Enviar uma Mensagem de Modelo

Rastrear o Status da Mensagem usando Webhooks

1. Mensagem de Modelo Enviada

O webhook de mensagem de modelo enviada agora inclui informações sobre botões

Quais informações de botão estão incluídas?

Variante BSUID

2. Mensagem Entregue

3. Mensagem Lida

4. Mensagem Respondida

5. Mensagem Recebida

6. Falha na Mensagem de Modelo

Como configurar Webhooks no Wati

Notas Finais