> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Exemplos de Webhooks de Atualização de Mensagem do WhatsApp
> Entenda as atualizações de mensagens do WhatsApp enviadas, entregues, lidas e com falha.
Para o catálogo completo derivado do esquema, consulte [todos os exemplos](/pt/api-reference/guides/examples/webhook-examples/webhook-payload-examples).
## 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
Para configuração de endpoints, validação de assinatura e comportamento de novas tentativas, consulte [Configurar webhooks](/pt/api-reference/guides/api-fundamentals/configure-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
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates#per-user-marketing-template-message-limits).
## 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
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.ycloud.com/reference/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
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.ycloud.com/reference/whatsapp-errors) 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](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
* Não cobramos por mensagens com falha.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.