Exemplos de Webhook de Mensagens do Histórico do WhatsApp Business App

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

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

Para configuração do endpoint, validação de assinatura e comportamento de novas tentativas, consulte Configurar 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

Requisição

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

Requisição

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

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

Primeiros passos

Guias

Endpoints

Webhooks

Exemplos de Webhook de Mensagens do Histórico do WhatsApp Business App

O que é

Antes de começar

Como funciona

Requisição

Resposta

Mensagem de texto recebida (Inbound)

Requisição

Resposta

Explicação

Mensagem de texto enviada (Outbound)

Requisição

Resposta

Explicação

Fragmento (chunk) de histórico apenas de progresso

Requisição

Resposta

Explicação

​O que é

​Antes de começar

​Como funciona

​Requisição

​Resposta

​Mensagem de texto recebida (Inbound)

​Requisição

​Resposta

​Explicação

​Mensagem de texto enviada (Outbound)

​Requisição

​Resposta

​Explicação

​Fragmento (chunk) de histórico apenas de progresso

​Requisição

​Resposta

​Explicação

O que é

Antes de começar

Como funciona

Requisição

Resposta

Mensagem de texto recebida (Inbound)

Requisição

Resposta

Explicação

Mensagem de texto enviada (Outbound)

Requisição

Resposta

Explicação

Fragmento (chunk) de histórico apenas de progresso

Requisição

Resposta

Explicação