Passar para o conteúdo principal

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

Atualizado hoje

Resumo

Ao enviar mensagens de template usando a API da Wati, é importante rastrear o status delas - como enviada, entregue, lida, respondida ou falha. Isso ajuda você a entender o desempenho da mensagem, solucionar problemas e gerenciar as interações com os clientes de forma mais eficaz. Este guia explica como enviar uma mensagem de template e usar webhooks para rastrear seu ciclo de vida.

Instruções

Enviar uma mensagem de template

Para enviar uma mensagem de template usando a API da 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 todos os eventos de webhook. Salve este valor, pois ele vincula todas as atualizações de status da mensagem.

Rastrear o status da mensagem usando webhooks

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

1. Mensagem de template enviada

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

  • Evento: templateMessageSent_v2

  • 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

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

  • Evento: sentMessageDELIVERED_v2

  • 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

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

  • Evento: sentMessageREAD_v2

  • 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

  • Acionado quando: O destinatário responde à mensagem

  • Evento: sentMessageREPLIED_v2

  • 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

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

  • Evento: messageReceived

  • Status: Received

Caso de uso:

  • Rastrear respostas de usuários

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

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 template falhou

  • Acionado quando: A mensagem não é enviada

  • Evento: templateMessageFailed

  • Status: Failed

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==",
  "timestamp": "1665645642",
  "operatorEmail": "[email protected]"
}

Como configurar webhooks na Wati

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

  1. Faça login no painel da Wati

  2. Vá para Conectores → Webhooks

  3. Clique em Adicionar Webhook

  4. Insira o URL do seu webhook

  5. Defina o status como Ativado

  6. Selecione os eventos necessários:

    • Mensagem de Template Enviada

    • Entregue

    • Lida

    • Respondida

    • Falhou

Notas finais

  • Sempre armazene o localMessageId ao enviar mensagens

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

  • Combine vários eventos de webhook para construir um ciclo de vida completo da mensagem

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

Perguntas frequentes (FAQs)

Enviando mensagens de template

1. Como você envia uma mensagem de template usando a API da Wati?

Você pode enviar uma mensagem de template usando a API da Wati chamando o endpoint sendTemplateMessage V2 com os cabeçalhos e o corpo JSON necessários, incluindo campos como template_name, broadcast_name e parameters.

2. Qual é o propósito do localMessageId na resposta da API?

O localMessageId é um identificador exclusivo retornado na resposta da API que é usado para rastrear a mensagem em todos os eventos de webhook. Este valor deve ser armazenado porque vincula todas as atualizações de status à mesma mensagem.

Rastreando o status da mensagem com webhooks

3. Como você pode rastrear o ciclo de vida de uma mensagem de template na Wati?

Você pode rastrear o ciclo de vida de uma mensagem de template usando eventos de webhook enviados pela Wati após o envio da mensagem. Cada evento de webhook inclui um localMessageId que permite corresponder o evento com a mensagem original e acompanhar suas atualizações de status.

4. Quais eventos de webhook são acionados para diferentes status de mensagem de template?

A Wati aciona os seguintes eventos de webhook para status de mensagem de template:

  • templateMessageSent_v2 quando a mensagem é enviada com sucesso (Status: SENT)

  • sentMessageDELIVERED_v2 quando a mensagem é entregue (Status: Delivered)

  • sentMessageREAD_v2 quando a mensagem é lida (Status: Read)

  • sentMessageREPLIED_v2 quando o destinatário responde (Status: Replied)

  • messageReceived quando um usuário envia uma mensagem para seu número Wati (Status: Received)

  • templateMessageFailed quando a mensagem não é enviada (Status: Failed)

5. Quando o evento de webhook messageReceived é acionado e qual é o seu uso?

O evento de webhook messageReceived é acionado quando um usuário envia uma mensagem para o seu número Wati. Ele pode ser usado para rastrear respostas de usuários e capturar cliques de botões de resposta rápida de mensagens de template.

Configuração de webhook

6. Como você configura webhooks na Wati para receber eventos de status de mensagem?

Para configurar webhooks na Wati:

  • Faça login no painel da Wati.

  • Vá para Conectores → Webhooks.

  • Clique em Adicionar Webhook.

  • Insira o URL do seu webhook.

  • Defina o status como Ativado.

  • Selecione os eventos necessários, como Mensagem de Template Enviada, Entregue, Lida, Respondida e Falhou.

Melhores práticas para rastreamento de mensagens

7. Por que você deve armazenar o localMessageId ao enviar mensagens?

Você deve armazenar o localMessageId porque ele é necessário para mapear todos os eventos de webhook para a mesma mensagem e rastrear seu ciclo de vida completo.

8. Como você pode construir um ciclo de vida completo da mensagem usando eventos de webhook?

Você pode construir um ciclo de vida completo da mensagem combinando vários eventos de webhook vinculados pelo mesmo localMessageId, que fornece todas as atualizações de status para uma única mensagem de template.

9. Por que a configuração do webhook é importante para rastrear mensagens de template na Wati?

A configuração do webhook é importante porque permite o rastreamento em tempo real de cada mensagem de template enviada através da Wati e permite que você tome medidas com base em atualizações de status, como enviada, entregue, lida, respondida ou falhou.

Artigos relacionados
Como enviar mensagens de WhatsApp usando webhooks do Zapier e Wati
Como integrar o Wati com o Kylas CRM
Como notificar clientes usando o modelo de status do pedido Wati API
Perguntas frequentes em geral: Wati APIs e Webhooks
Como configurar e usar webhooks no Wati
Respondeu à sua pergunta?