Passar para o conteúdo principal

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

Resumo

Ao enviar mensagens de modelo usando a Wati API, você pode querer rastrear seu status - como enviada, entregue, lida, respondida ou falha - usando webhooks em vez de depender apenas das análises de campanha integradas da Wati.

Após o envio de campanhas via API, você sempre pode visualizar o desempenho delas na Visão Geral da Campanha no Wati. No entanto, você também pode usar os webhooks do Wati para rastrear o status da mensagem e eventos de entrega dessas campanhas em tempo real por meio de seus próprios sistemas.

Essa abordagem ajuda você a monitorar o desempenho das mensagens, solucionar problemas de entrega e gerenciar as interações com os clientes através de suas aplicações. Este guia explica como enviar uma mensagem de modelo e rastrear seu ciclo de vida usando webhooks.

Nota: Para mais informações sobre webhooks do Wati, consulte a documentação para desenvolvedores do Wati.

Instruções

Enviar uma mensagem de modelo

Para enviar uma mensagem de modelo usando a API do Wati, use o endpoint sendTemplateMessage V2.

Exemplo de solicitação cURL

curl --location 'https://live-mt-server.wati.io/{tenant_id}/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 exclusivo usado para rastrear a mensagem em eventos de webhook. Salve este valor, pois ele vincula todas as atualizações de status da mensagem.

Rastrear o status da mensagem usando webhooks

Assim que a mensagem é enviada, o Wati envia eventos de webhook para cada atualização de status. Use o localMessageId para corresponder esses eventos à mensagem original.

1. Mensagem de modelo enviada

  • Acionado quando: A mensagem é enviada com sucesso do Wati

  • Evento: templateMessageSent_v2

  • Status: SENT (Enviada)

Exemplo de Payload de Webhook

{
  "eventType": "templateMessageSent_v2_bsuid",
  "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",
  "headerLink": null,
  "headerType": null,
  "channelId": null,
  "channelPhoneNumber": "174742",
  "bsuid": "HK.xxxxxxxxxxxxx",
  "parentBsuid": "HK.ENT.xxxxxxxxxxxxx",
  "username": "@bob"
}

O webhook de modelo enviado agora inclui informações de botão

O webhook de Modelo Enviado agora inclui informações de botão configuradas no modelo do WhatsApp. Isso permite identificar 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.

2. Mensagem entregue

  • Acionado quando: A mensagem é entregue ao destinatário

  • Evento: sentMessageDELIVERED_v2

  • Status: Delivered (Entregue)

Exemplo de Payload de Webhook

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

3. Mensagem lida

  • Acionado quando: O destinatário lê a mensagem

  • Evento: sentMessageREAD_v2

  • Status: Read (Lida)

Exemplo de Payload de Webhook

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

4. Mensagem respondida

  • Acionado quando: O destinatário responde à mensagem

  • Evento: sentMessageREPLIED_v2

  • Status: Replied (Respondida)

Exemplo de Payload de Webhook

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

5. Mensagem recebida

  • Acionado quando: Um usuário envia uma mensagem para o seu número Wati

  • Evento: messageReceived

  • Status: Received (Recebida)

Caso de uso:

  • Rastrear respostas de usuários

  • Capturar cliques em botões de resposta rápida de mensagens de modelo

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. Falha na mensagem de modelo

  • Acionado quando: O envio da mensagem falha

  • Evento: templateMessageFailed

  • Status: Failed (Falha)

Exemplo de Payload de Webhook

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

Como configurar webhooks no Wati

Siga estas etapas para começar a receber eventos de webhook:

  • Faça login na sua conta Wati

  • Vá para Conectores (Connectors) → Webhooks

  • Clique em Adicionar Webhook (Add Webhook)

  • Insira a URL do seu webhook

  • Defina o status como Ativado (Enabled)

  • Selecione os eventos necessários:

    • Mensagem de Modelo Enviada (Template Message Sent)

    • Entregue (Delivered)

    • Lida (Read)

    • Respondida (Replied)

    • Falha (Failed)

Notas finais

  • Sempre armazene o localMessageId ao enviar mensagens

  • Use-o para mapear todos os eventos de webhook para a mesma mensagem

  • Combine múltiplos eventos de webhook para construir o ciclo de vida completo da mensagem

Ao configurar os webhooks corretamente, você pode rastrear de forma confiável cada mensagem de modelo enviada através do Wati e agir com base em atualizações em tempo real.

Perguntas Frequentes (FAQs)

Envio e Rastreamento de Mensagens de Modelo

1. Como envio uma mensagem de modelo usando a API do Wati?

Use o endpoint sendTemplateMessage V2 para enviar uma mensagem de modelo através da API do Wati.

2. O que é o localMessageId e por que devo salvá-lo?

O localMessageId é um identificador exclusivo para uma mensagem. Salve-o porque o Wati o utiliza para vincular eventos de webhook à mensagem original e rastrear seu status ao longo de todo o ciclo de vida.

3. Como posso rastrear o status da mensagem de modelo usando webhooks do Wati?

Configure os webhooks do Wati para receber eventos em tempo real para mensagens de modelo. Use o localMessageId para corresponder cada evento de webhook com a mensagem original.

4. Quais eventos de webhook rastreiam o ciclo de vida da mensagem de modelo?

Os eventos de webhook disponíveis são:

  • templateMessageSent_v2 — a mensagem foi enviada com sucesso.

  • sentMessageDELIVERED_v2 — a mensagem foi entregue.

  • sentMessageREAD_v2 — o destinatário leu a mensagem.

  • sentMessageREPLIED_v2 — o destinatário respondeu à mensagem.

  • templateMessageFailed — o envio da mensagem falhou.

  • messageReceived — um usuário enviou uma mensagem para o seu número Wati.

5. Para que o webhook messageReceived pode ser usado?

O webhook messageReceived pode ser usado para rastrear respostas dos usuários e capturar cliques em botões de resposta rápida de mensagens de modelo.

6. Quais informações de botão estão incluídas no webhook de Modelo Enviado?

O webhook de Modelo Enviado pode incluir o texto do botão de resposta rápida e o texto do botão de link configurados no modelo do WhatsApp. A resposta da API para informações de modelo também inclui o texto do botão configurado.

7. Quais planos do Wati suportam informações de botão no webhook de Modelo Enviado?

O recurso de informações de botão está disponível para clientes nos planos Pro, Business e Enterprise.

8. Como configuro webhooks no Wati para rastrear mensagens de modelo?

Vá para Conectores → Webhooks em sua conta Wati, clique em Adicionar Webhook, insira a URL do seu webhook, defina o status como Ativado e selecione os eventos necessários: Mensagem de Modelo Enviada, Entregue, Lida, Respondida e Falha.

9. Como posso rastrear o ciclo de vida completo de uma mensagem de modelo?

Armazene o localMessageId ao enviar a mensagem e use-o para mapear todos os eventos de webhook relacionados. Combinar esses eventos permite rastrear se a mensagem foi enviada, entregue, lida, respondida ou se houve falha.

Artigos relacionados
Respondeu à sua pergunta?