Exemplos de webhook de status de mensagem

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

O que é

Gerencie atualizações de mensagens para WhatsApp, Messenger, Email, SMS e Voice.

Antes de começar

Crie um endpoint HTTPS público em sua aplicação.
Configure um endpoint de webhook da YCloud para os tipos de evento de que você precisa.
Armazene o segredo de assinatura do endpoint com segurança.
Torne o processamento de eventos idempotente.

Como funciona

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

Solicitação

Os cenários abaixo mostram solicitações entregues à URL do seu webhook. Trate o id do evento como o identificador de entrega e use type para rotear o payload.

Resposta

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

HTTP/1.1 200 OK

Para configuração do endpoint, validação de assinatura e comportamento de repetição, consulte Configurar webhooks.

Para o WhatsApp, após solicitar o envio de mensagens com sucesso via API, as mensagens ficam com o status accepted. As atualizações de status de mensagem acionarão o webhook whatsapp.message.updated. Normalmente, o status da mensagem:

Muda para failed se não pudermos entregar esta mensagem.
Muda para sent se for possível entregar esta mensagem, e mais tarde 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 delivered podem acontecer após failed, e vice-versa, especialmente quando o usuário final está usando vários 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 dentro dos sistemas do WhatsApp.
Contém informações sobre a conversa, incluindo o momento em que a conversa expira e o tipo de origem.
Contém o pricingCategory e a totalPrice estimados que podemos cobrar de você.
Contém wamid, que é o ID original da mensagem na plataforma do WhatsApp, começando com wamid..

Solicitaçã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 de a primeira mensagem ser entregue, tornando-se o preço final quando o status for delivered ou read. O saldo ocupado pelas mensagens enviadas, mas ainda não entregues, não ficará disponível até que as mensagens sejam descartadas (mensagens enviadas que não forem entregues por 30 dias são descartadas).
Geralmente, uma mensagem sent muda para delivered ou read em breve, exceto se:
- A conta do WhatsApp do destinatário estiver offline; suas mensagens enviadas do WhatsApp não serão entregues até que o destinatário tenha conexão de internet ativa ou funcionando.
- Qualquer mensagem enviada para um contato que bloqueou você sempre exibirá o sent da mensagem e nunca mudará para delivered.
- O destinatário desativou as confirmações de leitura, e você não receberá as confirmações de read da mensagem.
- A mensagem mudar 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” (O destinatário é incapaz de receber esta mensagem). O mais provável é que o destinatário não esteja cadastrado ou esteja usando uma versão antiga do WhatsApp.
- A mensagem não foi entregue para preservar uma experiência de usuário de alta qualidade. Consulte Limites de modelos de mensagem 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.

Solicitaçã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 cenários semelhantes, a notificação delivered não será enviada de volta, pois subentende-se que uma mensagem foi entregue se ela foi lida. O motivo desse comportamento é uma 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 vários dispositivos.
pricingModel: “PMP” — indica que a cobrança por mensagem é aplicável. 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 status da mensagem é 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á as confirmações de mensagem read.

Falha na mensagem

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

O status status da mensagem é 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 notificar você sobre mudanças de status em mensagens de saída enviadas anteriormente aos clientes.
O motivo da falha no envio geralmente se deve a parâmetros de solicitação inválidos, ao número de telefone do cliente não estar registrado, etc. Consulte também Erros do WhatsApp para tratamento de erros.
whatsappApiError é fornecido caso tenhamos tentado enviar essa mensagem para a plataforma WhatsApp da Meta para ajudar você a entender os detalhes do erro. Consulte também os Códigos de erro da Cloud API.
Nós não cobramos por mensagens com falha.

Atualização de entrega de e-mail

Use email.delivery.updated quando o status de entrega de um e-mail mudar para delivered ou failed.

Requisição

{
  "id": "evt_example_email_delivery_updated",
  "type": "email.delivery.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "emailDelivery": {
    "emailId": "email_12345678",
    "recipientAddress": "customer@example.com",
    "status": "delivered",
    "externalId": "order_123"
  }
}

Resposta

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

HTTP/1.1 200 OK

Explicação

Correlacione a entrega com emailId e recipientAddress: o status se aplica a este destinatário. Use externalId quando fornecido para corresponder ao seu próprio registro. Inspecione errorCode e errorMessage em uma falha de entrega. A propriedade do payload é emailDelivery, não whatsappMessage.

Atualização de entrega de SMS

Use sms.message.updated quando o status de entrega de um SMS mudar para delivered ou undelivered.

Requisição

{
  "id": "evt_example_sms_message_updated",
  "type": "sms.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "sms": {
    "id": "sms_12345678",
    "to": "+16315551111",
    "status": "delivered",
    "externalId": "order_123"
  }
}

Resposta

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

HTTP/1.1 200 OK

Explicação

Identifique o SMS com sms.id e leia sms.status. Inspecione errorCode quando a entrega falhar. O SMS usa undelivered para um comprovante de entrega negativo; não aplique o modelo de status read do WhatsApp a este evento.

Atualização de entrega de voz

Use voice.message.updated quando o status de uma mensagem de voz mudar para delivered ou undelivered.

Requisição

{
  "id": "evt_example_voice_message_updated",
  "type": "voice.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "voice": {
    "id": "voice_12345678",
    "to": "+16315551111",
    "status": "delivered",
    "externalId": "verification_123"
  }
}

Resposta

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

HTTP/1.1 200 OK

Explicação

Identifique a mensagem de voz com voice.id e leia voice.status. Inspecione errorCode quando fornecido. Esse evento de entrega pertence à API de mensagens de Voz; ele é separado dos eventos do ciclo de vida de chamadas do WhatsApp Calling.

Snapshot de leitura de saída do Messenger

Inscreva-se em messenger.message.updated para snapshots salvos de mensagens de saída individuais comuns. Uma nova tentativa de entrega mantém Event.id; recriar um evento a partir do mesmo fato de origem pode produzir um novo Event.id. Correlacione as atualizações por messengerMessage.id.

Estados de envio e recebimento

accepted significa que a Meta aceitou o envio, não que a mensagem foi sent ou delivered. rejected é uma rejeição definitiva de envio; unknown é um resultado não confirmado e não deve ser tratado como falha. Não reenvie uma mensagem automaticamente após um tempo limite ou um resultado unknown. Verifique o status salvo usando o ID da mensagem retornado quando disponível, ou entre em contato com o suporte. Um snapshot preserva os fatos atualmente salvos, com read tendo precedência sobre delivered, sent e o resultado do envio. Confirmações tardias não rebaixam esse estado. Você pode receber snapshots repetidos ou perder estados intermediários. Use GET /v2/messenger/messages/{id} com from, ou recupere pelo ID de mensagem confirmado da Meta, para reconciliar seu estado salvo atual. As notificações de resultado de envio são feitas com base no melhor esforço. Não dependa do recebimento de um webhook para cada resultado síncrono de envio. IDs opcionais, errorCode e horários de recebimento são omitidos quando indisponíveis. Um erro de envio armazenado pode permanecer presente mesmo após confirmações posteriores estabelecerem um estado mais forte.

Requisição

{
  "id": "evt_89abcdef0123456789abcdef",
  "type": "messenger.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:03.000Z",
  "messengerMessage": {
    "id": "1308528868252065792",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "from": "422500000000000",
    "to": "100800000000000",
    "type": "text",
    "text": {
      "body": "How can I help you?"
    },
    "status": "read",
    "createTime": "2026-10-20T02:00:00.000Z",
    "updateTime": "2026-10-20T02:00:03.000Z",
    "readTime": "2026-10-20T02:00:03.000Z"
  }
}

Resposta

HTTP/1.1 200 OK

Explicação

O ID da Página do Facebook é from e o PSID do cliente é to. Este exemplo expõe o estado salvo read sem inventar sendTime ou deliverTime ausentes. id é o ID da mensagem na YCloud, enquanto metaMessageId é a identidade do provedor.

Reação a mensagem do Messenger

Requisição

{
  "id": "evt_abcdef0123456789abcdef01",
  "type": "messenger.message_reaction.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:04.000Z",
  "messengerMessageReaction": {
    "pageId": "422500000000000",
    "psid": "100800000000000",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "action": "react",
    "reaction": "love",
    "emoji": "❤️"
  }
}

Resposta

HTTP/1.1 200 OK

Explicação

Use pageId e psid para identificar a conversa e metaMessageId para identificar a mensagem de destino. Uma reação é uma interação e não altera o status de entrega. O destino pode não ter um registro de mensagem local na YCloud. Preserve o createTime de origem; entregas repetidas podem ocorrer. Verifique YCloud-Signature em relação ao corpo bruto (raw body) antes de retornar uma resposta de sucesso.

Reação à mensagem do Messenger removida

Solicitação

{
  "id": "evt_bcdef0123456789abcdef012",
  "type": "messenger.message_reaction.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:05.000Z",
  "messengerMessageReaction": {
    "pageId": "422500000000000",
    "psid": "100800000000000",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "action": "unreact"
  }
}

Resposta

HTTP/1.1 200 OK

Explicação

Remova a reação associada a esta Página, PSID do cliente e mensagem de destino da Meta. unreact pode omitir reaction e emoji. Não exija um ID de mensagem local nem deduza uma alteração de status da mensagem. Tentativas de entrega HTTP mantêm o mesmo ID de evento e corpo; callbacks de origem repetidos podem criar um novo ID de evento. Verifique YCloud-Signature em relação ao corpo bruto (raw body) antes de retornar uma resposta de sucesso.

​O que é

​Antes de começar

​Como funciona

​Solicitação

​Resposta

​Mensagem enviada

​Solicitação

​Resposta

​Explicação

​Mensagem entregue

​Solicitação

​Resposta

​Explicação

​Mensagem lida

​Requisição

​Resposta

​Explicação

​Falha na mensagem

​Requisição

​Resposta

​Explicação

​Atualização de entrega de e-mail

​Requisição

​Resposta

​Explicação

​Atualização de entrega de SMS

​Requisição

​Resposta

​Explicação

​Atualização de entrega de voz

​Requisição

​Resposta

​Explicação

​Snapshot de leitura de saída do Messenger

​Estados de envio e recebimento

​Requisição

​Resposta

​Explicação

​Reação a mensagem do Messenger

​Requisição

​Resposta

​Explicação

​Reação à mensagem do Messenger removida

​Solicitação

​Resposta

​Explicação

O que é

Antes de começar

Como funciona

Solicitação

Resposta

Mensagem enviada

Solicitação

Resposta

Explicação

Mensagem entregue

Solicitação

Resposta

Explicação

Mensagem lida

Requisição

Resposta

Explicação

Falha na mensagem

Requisição

Resposta

Explicação

Atualização de entrega de e-mail

Requisição

Resposta

Explicação

Atualização de entrega de SMS

Requisição

Resposta

Explicação

Atualização de entrega de voz

Requisição

Resposta

Explicação

Snapshot de leitura de saída do Messenger

Estados de envio e recebimento

Requisição

Resposta

Explicação

Reação a mensagem do Messenger

Requisição

Resposta

Explicação

Reação à mensagem do Messenger removida

Solicitação

Resposta

Explicação