Passar para o conteúdo principal

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

Atualizado há mais de uma semana

Resumo

Ao enviar mensagens de modelo usando a API Wati, você pode querer rastrear o status delas - como enviada, entregue, lida, respondida ou falha - usando webhooks em vez de confiar apenas na análise de campanha integrada do Wati.

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

Essa abordagem ajuda você a monitorar o desempenho da mensagem, solucionar problemas de entrega e gerenciar interações com clientes por meio de seus aplicativos. Este guia explica como enviar uma mensagem de modelo e rastrear seu ciclo de vida usando webhooks.

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 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 for enviada, o Wati enviará eventos de webhook para cada atualização de status. Use o localMessageId para corresponder esses eventos com a mensagem original.

1. Mensagem de modelo enviada

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

  • Evento: templateMessageSent_v2

  • Status: SENT

Exemplo de carga 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 carga 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 carga 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 carga 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 o 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 modelo

Exemplo de carga 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: A mensagem não é enviada

  • Evento: templateMessageFailed

  • Status: Failed

Exemplo de carga 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 no Wati

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

  1. Faça login no painel do Wati

  2. Vá para Conectores → Webhooks

  3. Clique em Adicionar Webhook

  4. Insira seu URL de webhook

  5. Defina o status como Ativado

  6. Selecione os eventos obrigatórios:

    • Modelo de mensagem 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 criar um ciclo de vida completo da mensagem

Ao configurar os webhooks corretamente, você pode rastrear de forma confiável todas as mensagens de modelo enviadas pelo Wati e tomar medidas com base em atualizações em tempo real.

Perguntas frequentes (FAQs)

Enviando mensagens de modelo

1. Como você envia uma mensagem de modelo usando a API do Wati?

Você pode enviar uma mensagem de modelo usando a API do 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 objetivo 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 modelo no Wati?

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

4. Quais eventos de webhook são acionados para diferentes status de mensagens de modelo?

O Wati aciona os seguintes eventos de webhook para status de mensagens de modelo:

  • 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 o 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 do usuário e capturar cliques de botões de resposta rápida de mensagens de modelo.

Configuração de webhook

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

Para configurar webhooks no Wati:

  • Faça login no painel do Wati.

  • Vá para Conectores → Webhooks.

  • Clique em Adicionar Webhook.

  • Insira seu URL de webhook.

  • Defina o status como Ativado.

  • Selecione os eventos obrigatórios, como Modelo de mensagem enviada, Entregue, Lida, Respondida e Falha.

Práticas recomendadas 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 modelo.

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

A configuração do webhook é importante porque permite o rastreamento em tempo real de todas as mensagens de modelo enviadas pelo Wati e permite que você tome medidas com base em atualizações de status, como enviada, entregue, lida, respondida ou falha.

Artigos relacionados
Integrando Wati com Bitrix24
Como enviar mensagens de WhatsApp usando webhooks do Zapier e Wati
Como configurar webhooks para múltiplos números de WhatsApp no Wati
Perguntas frequentes em geral: Wati APIs e Webhooks
Como configurar e usar webhooks no Wati
Respondeu à sua pergunta?