Exemplos de Webhooks de Atualização de Mensagem do WhatsApp

Para o catálogo completo derivado do esquema, consulte todos os exemplos.

O que é

Entenda as atualizações de mensagens do WhatsApp enviadas, entregues, lidas e com falha.

Antes de começar

Crie um endpoint HTTPS público na sua aplicação.
Configure um endpoint de webhook da YCloud para os tipos de eventos necessários.
Armazene o segredo de assinatura do endpoint com segurança.
Torne o processamento de eventos idempotente.

Como funciona

A YCloud envia uma requisição HTTP POST quando o evento ocorre. Valide a assinatura, registre o evento de forma durável, retorne uma resposta 2xx e processe tarefas lentas de forma assíncrona.

Requisição

Os cenários abaixo mostram requisições entregues ao seu URL de webhook. Trate o id do evento como o identificador de entrega e use o type para rotear a carga útil.

Resposta

Retorne um status 2xx após aceitar o evento.

HTTP/1.1 200 OK

Para configuração de endpoints, validação de assinatura e comportamento de novas tentativas, consulte Configurar webhooks.

Após solicitar com sucesso à API o envio de mensagens, as mensagens recebem o status de accepted. As atualizações de status da mensagem acionarão o webhook whatsapp.message.updated. Geralmente, o status da mensagem:

Muda para failed se não conseguirmos entregar esta mensagem.
Muda para sent se for possível entregar esta mensagem e, posteriormente, pode mudar para failed, delivered ou read.
Muda para delivered ou read se esta mensagem foi entregue ao dispositivo do destinatário.

Mas a situação real é complexa. Primeiro, não garantimos a ordem das notificações de webhook, especialmente quando os eventos ocorrem quase simultaneamente. Segundo, eventos de delivered podem ocorrer após failed, e vice-versa, especialmente quando o usuário final está usando múltiplos dispositivos.

Mensagem Enviada

Neste caso, seu endpoint de webhook recebeu um evento de mensagem sent:

O status da mensagem é sent, o que significa que a mensagem está em trânsito nos sistemas do WhatsApp.
Contém informações sobre a conversa, incluindo quando a conversa expira e o tipo de origem.
Contém o pricingCategory e a totalPrice estimados que poderemos cobrar de você.
Contém wamid, que é o ID original da mensagem na plataforma do WhatsApp, começando com wamid..

Requisição

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M."
    },
    "status": "sent",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

totalPrice é apenas um preço estimado antes que a primeira mensagem seja entregue, e torna-se o preço final quando o status for delivered ou read. O saldo retido por mensagens enviadas que ainda não foram entregues não estará disponível até que as mensagens sejam descartadas (mensagens enviadas não entregues por 30 dias são descartadas).
Em geral, uma mensagem sent muda para delivered ou read em breve, exceto quando:
- A conta do WhatsApp do destinatário está offline; as mensagens enviadas do WhatsApp não serão entregues até que o destinatário tenha conexão de internet ativa ou funcional.
- Qualquer mensagem enviada para um contato que bloqueou você sempre exibirá a mensagem como sent e nunca mudará para delivered.
- O destinatário desativou as confirmações de leitura, e você não receberá as confirmações de mensagem read.
- A mensagem muda para failed mais tarde com o código de erro 131026, o que significa “Message Undeliverable” (Mensagem Não Entregável) ou “Receiver is incapable of receiving this message” (Destinatário incapaz de receber esta mensagem). É muito provável que o destinatário não esteja registrado ou esteja usando uma versão antiga do WhatsApp.
- A mensagem não foi entregue para manter uma experiência de usuário de alta qualidade. Consulte Limites de Mensagens de Modelo de Marketing por Usuário.

Mensagem Entregue

Neste caso, seu endpoint de webhook recebeu um evento de mensagem delivered:

O status da mensagem é delivered, o que significa que a mensagem foi entregue ao dispositivo do destinatário.

Requisição

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M.",
      "username": "@pablomorales"
    },
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "deliverTime": "2022-03-01T12:00:02.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Este evento indica que a mensagem enviada pela sua empresa foi entregue ao dispositivo do usuário.
Para que um status seja read, ele deve ter sido delivered. Em alguns cenários, como quando um usuário está na tela de conversa e uma mensagem chega, a mensagem é delivered e read quase simultaneamente. Neste ou em outros cenários semelhantes, a notificação delivered não será enviada de volta, pois fica implícito que uma mensagem foi entregue se tiver sido lida. O motivo desse comportamento é otimização interna.
É possível que geremos mais de 1 evento de webhook delivered para a mesma mensagem, especialmente se o usuário final estiver usando múltiplos dispositivos.
pricingModel: “PMP” — indica que o modelo de preço por mensagem se aplica. Consulte também whatsapp-message-pricing-updates
pricingType
- regular — indica que a mensagem é faturável.
- free_customer_service — indica que a mensagem é gratuita porque foi uma mensagem de modelo de utilidade ou uma mensagem sem modelo enviada dentro de uma janela de atendimento ao cliente.
- free_entry_point — indica que a mensagem é gratuita porque faz parte de uma conversa de ponto de entrada gratuito.

Mensagem lida

Nesse caso, seu endpoint de Webhook recebeu um evento de mensagem read:

O status da mensagem status é read, o que significa que a mensagem foi lida pelo destinatário.

Requisição

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M.",
      "username": "@pablomorales"
    },
    "status": "read",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "deliverTime": "2022-03-01T12:00:02.000Z",
    "readTime": "2022-03-01T12:00:02.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Se o destinatário tiver desativado as confirmações de leitura, você não receberá os recibos de mensagem read.

Falha na mensagem

Nesse caso, seu endpoint de Webhook recebeu um evento de mensagem failed:

O status da mensagem status é failed.
Contém errroCode, errorMessage e whatsappApiError.

Requisição

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "status": "failed",
    "errorCode": "100",
    "errorMessage": "Parameter Invalid",
    "whatsappApiError": {
      "message": "(#100) Invalid parameter",
      "type": "OAuthException",
      "code": "100",
      "fbtrace_id": "AwmiSOCojlAkqvjCTjGt37r",
      "error_data": {
        "messaging_product": "whatsapp",
        "details": "Parameter Invalid"
      }
    },
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Esses eventos têm como objetivo notificá-lo sobre alterações de status das mensagens ativas que você enviou anteriormente aos clientes.
O motivo da falha no envio da mensagem geralmente decorre de parâmetros de requisição inválidos, número de telefone do cliente não registrado, etc. Consulte também Erros do WhatsApp para tratamento de erros.
whatsappApiError é fornecido caso tenhamos tentado enviar esta mensagem para a plataforma WhatsApp da Meta para ajudar você a entender os detalhes do erro. Consulte também Códigos de erro da Cloud API.
Não cobramos por mensagens com falha.

Primeiros passos

Guias

Endpoints

Webhooks

Exemplos de Webhooks de Atualização de Mensagem do WhatsApp

O que é

Antes de começar

Como funciona

Requisição

Resposta

Mensagem Enviada

Requisição

Resposta

Explicação

Mensagem Entregue

Requisição

Resposta

Explicação

Mensagem lida

Requisição

Resposta

Explicação

Falha na mensagem

Requisição

Resposta

Explicação

​O que é

​Antes de começar

​Como funciona

​Requisição

​Resposta

​Mensagem Enviada

​Requisição

​Resposta

​Explicação

​Mensagem Entregue

​Requisição

​Resposta

​Explicação

​Mensagem lida

​Requisição

​Resposta

​Explicação

​Falha na mensagem

​Requisição

​Resposta

​Explicação

O que é

Antes de começar

Como funciona

Requisição

Resposta

Mensagem Enviada

Requisição

Resposta

Explicação

Mensagem Entregue

Requisição

Resposta

Explicação

Mensagem lida

Requisição

Resposta

Explicação

Falha na mensagem

Requisição

Resposta

Explicação