> ## 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 Webhook de Mensagens do Histórico do WhatsApp Business App
> Processe eventos de sincronização de histórico do WhatsApp Business App.
Para consultar o catálogo completo derivado do esquema, consulte [todos os exemplos](/pt/api-reference/guides/examples/webhook-examples/webhook-payload-examples).
## O que é
Processe eventos de sincronização de histórico do WhatsApp Business App.
## 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 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. Verifique a assinatura, registre o evento de forma durável, retorne uma resposta `2xx` e processe tarefas demoradas de forma assíncrona.
Para eventos criados a partir de um fragmento (chunk) de histórico da Meta, a YCloud copia o `phase` e o `progress` do chunk para o evento de nível superior. Os chunks que contêm mensagens incluem um objeto de mensagem específico da direção. Se tanto `threads` quanto `errors` estiverem vazios, a YCloud enviará um evento exclusivo de progresso sem `whatsappMessage` ou `whatsappInboundMessage`.
As entregas ocorrem pelo menos uma vez (at-least-once) e podem chegar fora de ordem. Elimine duplicatas usando o `id` do evento; não use `phase` e `progress` como chave única de entrega.
## Requisição
Os cenários abaixo mostram as requisições entregues na URL do seu webhook. Trate o `id` do evento como o identificador de entrega e use `type` para rotear a carga útil (payload).
## 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 do endpoint, validação de assinatura e comportamento de novas tentativas, consulte [Configurar webhooks](/pt/api-reference/guides/api-fundamentals/configure-webhooks).
## Mensagem de texto recebida (Inbound)
Neste caso, o endpoint do seu webhook recebeu uma mensagem de texto de entrada:
* Contém o texto sem formatação que o usuário enviou.
* Contém as informações da mensagem mencionada em `context`.
* Para outros tipos de mensagens, consulte [whatsappInboundMessage](/pt/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples)
### 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_eEkn26qar3nOB8md",
"type": "whatsapp.smb.history",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"phase": 1,
"progress": 40,
"whatsappInboundMessage": {
"id": "63f872f6741c165b4342a751",
"wamid": "wamid.HBgNODi...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId": "US.13491208655302741918",
"fromParentUserId": "US.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeWick"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "text",
"text": {
"body": "OK"
},
"context": {
"from": "447901614024",
"id": "wamid.HBgNODr..."
}
}
}'
```
### 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
* **Mensagens recebidas (inbound) são aquelas enviadas por clientes para os números de telefone da sua empresa.**
* O `context` (opcional) contém as informações da mensagem mencionada, normalmente usada para responder a uma mensagem anterior enviada pelo usuário ou pela sua empresa.
* `context.from` é o ID do WhatsApp (número de telefone sem o prefixo '+') do usuário que enviou a mensagem mencionada.
* `context.id` é o ID original da mensagem mencionada na plataforma do WhatsApp, começando com `wamid.`.
## Mensagem de texto enviada (Outbound)
Neste caso, o endpoint do seu webhook recebeu uma mensagem de texto enviada por um cliente empresarial para um usuário do WhatsApp com o aplicativo WhatsApp Business ou dispositivo complementar compatível:
* Contém o texto sem formatação enviado anteriormente.
* Contém as informações da mensagem mencionada em `context`.
* Para outros tipos de mensagens, consulte [Exemplos de Webhook de Sincronização de Mensagens Enviadas pelo WhatsApp Business App](/pt/api-reference/guides/examples/webhook-examples/whatsapp-business-app-sent-message-sync-webhook-examples)
### 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.smb.history",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"phase": 1,
"progress": 40,
"whatsappMessage": {
"id": "63f5d602367ea403f8175a6c",
"wamid": "wamid.BgNODYxN...",
"status": "sent",
"from": "BUSINESS-PHONE-NUMBER",
"to": "CUSTOMER-PHONE-NUMBER",
"toUserId" : "US.13491208655302741918",
"toParentUserId": "US.11815799212886844830",
"wabaId": "WABA-ID",
"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?"
},
"context": {
"message_id": "wamid.BgNODYxN..."
}
}
}'
```
### 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
Roteie o evento por `type`, desduplique-o por `id` e transfira tarefas lentas ou propensas a falhas para um processador assíncrono.
## Fragmento (chunk) de histórico apenas de progresso
Quando um chunk de histórico da Meta não contém conversas nem erros, o evento ainda informa seus metadados de sincronização. O evento não contém uma carga útil (payload) de mensagem.
### 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_progressOnly73",
"type": "whatsapp.smb.history",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:02.000Z",
"phase": 1,
"progress": 73
}'
```
### Resposta
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### Explicação
Este evento intencionalmente não possui um objeto de mensagem do WhatsApp. Continue acompanhando o progresso e confirme a entrega como em qualquer outro webhook.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.