Exemplos de webhook de sincronização de mensagens enviadas do aplicativo WhatsApp Business

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

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/1.1 200 OK

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

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

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

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

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

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

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

{
  "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/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.

Primeiros passos

Guias

Endpoints

Webhooks

Exemplos de webhook de sincronização de mensagens enviadas do aplicativo WhatsApp Business

O que é

Antes de começar

Como funciona

Solicitação

Resposta

Mensagem de texto de saída

Solicitação

Resposta

Explicação

Mensagem de imagem de saída

Solicitação

Resposta

Explicação

Mensagem de vídeo de saída

Solicitação

Resposta

Explicação

Mensagem de áudio de saída

Solicitação

Resposta

Explicação

Mensagem de documento de saída

Solicitação

Resposta

Explicação

Mensagem do aplicativo Business criada

Solicitação

Resposta

Explicação

​O que é

​Antes de começar

​Como funciona

​Solicitação

​Resposta

​Mensagem de texto de saída

​Solicitação

​Resposta

​Explicação

​Mensagem de imagem de saída

​Solicitação

​Resposta

​Explicação

​Mensagem de vídeo de saída

​Solicitação

​Resposta

​Explicação

​

​Mensagem de áudio de saída

​Solicitação

​Resposta

​Explicação

​Mensagem de documento de saída

​Solicitação

​Resposta

​Explicação

​Mensagem do aplicativo Business criada

​Solicitação

​Resposta

​Explicação

O que é

Antes de começar

Como funciona

Solicitação

Resposta

Mensagem de texto de saída

Solicitação

Resposta

Explicação

Mensagem de imagem de saída

Solicitação

Resposta

Explicação

Mensagem de vídeo de saída

Solicitação

Resposta

Explicação

Mensagem de áudio de saída

Solicitação

Resposta

Explicação

Mensagem de documento de saída

Solicitação

Resposta

Explicação

Mensagem do aplicativo Business criada

Solicitação

Resposta

Explicação