> ## 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 sincronização de mensagens enviadas do aplicativo WhatsApp Business

> Processe eventos de sincronização de mensagens enviadas pelo aplicativo WhatsApp Business.

> [!NOTE]
>
> Para o catálogo exaustivo derivado do esquema, consulte [todos os exemplos](https://docs.ycloud.com/pt/api-reference/guides/examples/webhook-examples/webhook-payload-examples).

## O que é

Processe eventos de sincronização de mensagens enviadas pelo aplicativo WhatsApp Business.

## 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 necessários.
* 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 as solicitações entregues à sua URL de 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

> [!NOTE]
>
> Para configuração de endpoints, validação de assinatura e comportamento de novas tentativas, consulte [Configurar webhooks](https://docs.ycloud.com/pt/api-reference/guides/api-fundamentals/configure-webhooks.md).

## Mensagem de texto de saída

Neste caso, seu endpoint de webhook recebeu uma mensagem de texto de saída enviada por um cliente comercial a um usuário do WhatsApp com o aplicativo WhatsApp Business ou um dispositivo complementar compatível:

Leia o texto enviado de `whatsappMessage.text.body`.

### Solicitação

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_example_smb_echoes",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "text",
    "text": {
      "body": "Your order is ready for pickup."
    },
    "status": "sent",
    "createTime": "2026-10-08T12:00:00.000Z",
    "sendTime": "2026-10-08T12:00:00.000Z",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "username": "example_customer"
    }
  }
}'
```

### 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`, elimine duplicatas por `id` e transfira tarefas lentas ou sujeitas a falhas para um processador assíncrono.

## Mensagem de imagem de saída

Neste caso, seu endpoint de webhook recebeu uma mensagem de imagem de saída enviada por um cliente comercial a um usuário do WhatsApp com o aplicativo WhatsApp Business ou dispositivo complementar compatível.:

* Contém a imagem enviada anteriormente.

### Solicitaçã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.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "image",
    "image": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "image/jpeg"
    }
  }
}'
```

### 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

* O `image.link` pode ser acessado diretamente dentro de alguns minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalho `X-API-Key` para baixar este arquivo dentro de 30 dias.

## Mensagem de vídeo de saída

Neste caso, seu endpoint de webhook recebeu uma mensagem de vídeo de saída enviada por um cliente comercial a um usuário do WhatsApp com o aplicativo WhatsApp Business ou dispositivo complementar compatível.:

* Contém o vídeo enviado anteriormente.

### Solicitaçã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.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "video",
    "video": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "video/mp4"
    }
  }
}'
```

### 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

* O `video.link` pode ser acessado diretamente dentro de alguns minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalho `X-API-Key` para baixar este arquivo dentro de 30 dias.

##

## Mensagem de áudio de saída

Neste caso, seu endpoint de webhook recebeu uma mensagem de áudio de saída enviada por um cliente comercial a um usuário do WhatsApp com o aplicativo WhatsApp Business ou dispositivo complementar compatível.:

* Contém o áudio enviado anteriormente.

### Solicitaçã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.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "audio",
    "audio": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "audio/ogg; codecs=opus"
    }
  }
}'
```

### 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

* O `audio.link` pode ser acessado diretamente dentro de alguns minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalho `X-API-Key` para baixar este arquivo dentro de 30 dias.

## Mensagem de documento de saída

Neste caso, seu endpoint de webhook recebeu uma mensagem de documento de saída enviada por um cliente comercial a um usuário do WhatsApp com o aplicativo WhatsApp Business ou dispositivo complementar compatível.:

* Contém o documento enviado anteriormente.

### Solicitaçã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.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "document",
    "document": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "caption": "图片",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "image/jpeg"
    }
  }
}'
```

### 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

* O `document.link` pode ser acessado diretamente dentro de alguns minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalho `X-API-Key` para baixar este arquivo dentro de 30 dias.

## Mensagem do aplicativo Business criada

Use `whatsapp.smb.message.created` quando uma mensagem do aplicativo WhatsApp Business for enviada.

### Solicitação

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_smb_created",
  "type": "whatsapp.smb.message.created",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "text",
    "text": {
      "body": "Your order is ready for pickup."
    },
    "status": "sent",
    "createTime": "2026-10-08T12:00:00.000Z",
    "sendTime": "2026-10-08T12:00:00.000Z"
  }
}
```

### 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

Leia a mensagem de saída de `whatsappMessage`. Seu `type` seleciona o objeto de conteúdo; este exemplo de texto usa `text.body`. Roteie este evento separadamente de `whatsapp.smb.message.echoes` enquanto compartilha o parsing de mensagens onde apropriado. Esses são eventos de coexistência do aplicativo Business, não eventos de eco do agente de negócios da Meta.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.