Webhook received

received dispara para cada mensagem recebida pelo número conectado — texto, mídia, reação, voto, resposta de botão — e também para eventos de chat (alguém entrou no grupo, mensagem apagada, chamada perdida), que chegam com notification em vez de conteúdo. O schema completo com todos os campos está na referência. Esta página explica como ler o payload.

Envelope

{
  "type": "received",
  "event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1X",
  "instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
  "momment": 1786968300000,
  "message_id": "3EB0A9C6D2F1E4B5A7C8",
  "phone": "5511988887777",
  "chat_lid": "98765432109876@lid",
  "sender_lid": "98765432109876@lid",
  "from_me": false,
  "from_api": false,
  "is_group": false,
  "is_newsletter": false,
  "is_edit": false,
  "forwarded": false,
  "broadcast": false,
  "waiting_message": false,
  "status": "RECEIVED",
  "chat_name": "Maria",
  "sender_name": "Maria",
  "text": { "message": "Olá! Tudo bem?" }
}

Campo	Descrição
`message_id`	Id da mensagem no WhatsApp. Use em `reply_to_message_id`, `read-message`, `send-reaction`, `forward-message`
`phone`	O chat: número do contato, `...-group` em grupos, `...@newsletter` em canais
`chat_lid`, `sender_lid`	LIDs quando conhecidos — guarde junto com o número (Identificadores)
`from_me`	`true` para mensagens enviadas pelo número (só chegam com `notify_sent_by_me` ligado)
`from_api`	Entre as `from_me`, distingue as enviadas pela API das digitadas no celular
`is_group`, `participant_phone`, `participant_lid`	Em grupos, quem enviou
`reference_message_id`	Mensagem que está sendo respondida
`is_edit`	A mensagem é a edição de uma anterior (mesmo `message_id`)
`forwarded`, `broadcast`	Encaminhada / veio de lista de transmissão
`waiting_message`	Placeholder: o conteúdo real ainda está sendo decifrado; um segundo evento chega com o conteúdo
`message_expiration_seconds`, `expires_at`	Mensagem temporária
`status`	`RECEIVED` para mensagens dos outros; para as suas, o último recibo conhecido

Conteúdo por tipo

Exatamente um dos blocos abaixo vem preenchido. Teste a presença do campo (if (event.image) …) em vez de olhar um campo “tipo”.

text

"text": { "message": "Olá! Tudo bem?" }

Quando o texto traz link com prévia, vêm também title, description, url e thumbnail_url.

image, video, audio, document, sticker

"image": {
  "mime_type": "image/jpeg",
  "url": "https://media.wabox.me/8f2a3c1e/2026/09/03/3EB0A9C6D2F1E4B5A7C9.jpg?X-Amz-Signature=...",
  "thumbnail_url": "https://media.wabox.me/.../3EB0A9C6D2F1E4B5A7C9.thumb.jpg?X-Amz-Signature=...",
  "caption": "olha isso",
  "width": 1080,
  "height": 1920,
  "view_once": false,
  "file_size": 245678,
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}

url é assinada e expira em 24 h. Copie o arquivo para o seu storage se precisar dele depois.
Se o download/decifração falhar, url vem ausente e download_error explica o motivo.
video: seconds, is_gif. audio: ptt (voice note) e seconds. document: file_name, title, page_count. sticker: animated.
view_once: true em mídia de visualização única — o WhatsApp não permite reencaminhar; trate como sensível.

location

"location": { "latitude": -23.5505, "longitude": -46.6333, "name": "Praça da Sé", "address": "Sé, São Paulo - SP", "url": "" }

contact e contacts

"contact": { "display_name": "João Silva", "vcard": "BEGIN:VCARD...END:VCARD", "phones": ["5511977776666"] }

Vários cartões numa mensagem chegam em contacts (array com o mesmo formato).

reaction

"reaction": {
  "value": "👍",
  "time": 1786968400000,
  "reaction_by": "5511988887777",
  "referenced_message": { "message_id": "3EB0A9C6D2F1E4B5A7C8", "from_me": true, "phone": "5511988887777" }
}

value vazio significa que a reação foi removida.

poll e poll_vote

"poll": { "question": "Qual horário?", "poll_max_options": 1, "options": [{ "name": "9h" }, { "name": "14h" }] }

"poll_vote": { "poll_message_id": "3EB0A9C6D2F1E4B5A7C8", "options": [{ "name": "14h" }] }

Votos só são decifrados para enquetes que o engine viu (enviadas pela API ou recebidas desde o último restart).

buttons_response e list_response

Resposta do contato a botões ou lista que você enviou:

"buttons_response": { "button_id": "yes", "message": "Sim" }

"list_response": { "selected_row_id": "plano_pro", "title": "Plano Pro", "message": "Plano Pro" }

reference_message_id aponta para a mensagem interativa original.

buttons e list (recebidos)

Mensagens interativas enviadas por outras contas (um negócio, por exemplo) chegam em buttons (message, title, footer, buttons[] com label, type, url/phone) ou list (sections[].rows[]).

event e event_response

"event": {
  "name": "Reunião de alinhamento",
  "description": "Sala 2",
  "start_at": "2026-09-10T14:00:00.000Z",
  "end_at": "2026-09-10T15:00:00.000Z",
  "location": { "name": "Escritório" },
  "canceled": false
}

"event_response": { "event_message_id": "3EB0A9C6D2F1E4B5A7E1", "response": "going", "extra_guests": 1 }

product e order (Business)

product traz o snapshot do card enviado (product_id, title, price, currency, business_phone…); order traz o pedido feito pelo cliente a partir do catálogo (order_id, token, item_count, status, total…). Use order_id + token em GET /business/orders/{id} para os itens. A imagem do produto não é baixada.

notification (eventos de chat)

Sem conteúdo de mensagem; notification diz o que aconteceu e notification_parameters traz os envolvidos:

`notification`	Significado
`REVOKE`	Mensagem apagada para todos (`reference_message_id` diz qual)
`GROUP_CREATE`, `GROUP_CHANGE_SUBJECT`, `GROUP_CHANGE_DESCRIPTION`, `GROUP_CHANGE_ICON`	Grupo criado / renomeado / descrição / foto
`GROUP_PARTICIPANT_ADD`, `_REMOVE`, `_PROMOTE`, `_DEMOTE`, `_LEAVE`, `_INVITE`	Mudanças de participantes (`notification_parameters` = números)
`MEMBERSHIP_APPROVAL_REQUEST`	Alguém pediu para entrar (aprove com `POST /groups/{id}/participants`)
`CALL_RECEIVED`, `CALL_MISSED`, `CALL_MISSED_VOICE`, `CALL_MISSED_VIDEO`	Chamadas — a API não atende; veja `call_reject_auto` nas configurações
`E2E_ENCRYPTED`, `CIPHERTEXT`	Aviso de criptografia / mensagem que não pôde ser decifrada ainda
`PROFILE_NAME_UPDATED`, `PROFILE_PICTURE_UPDATED`	Contato mudou nome/foto

unsupported

Tipo que o Wabox ainda não mapeia: "unsupported": { "wa_type": "…" }. Abra um chamado com o wa_type se precisar dele.

Mensagens enviadas por você

Por padrão, received não inclui o que o próprio número envia. Ligue notify_sent_by_me nos filtros para receber também as mensagens digitadas no celular e as enviadas pela API (from_me: true; from_api separa as duas). É útil para espelhar a conversa num CRM.

Grupos

phone é o id do grupo (120363012345678901-group) e participant_phone quem escreveu. Para responder no grupo, use o id do grupo em phone; para responder no privado, use participant_phone. Se o remetente usa número oculto, participant_phone pode vir no formato ...@lid — ele funciona igual como destino.

Dicas

Responda 200 e processe depois; um received de mídia pode pesar (a mídia em si não vai no payload, só a URL).
Baixe a mídia logo: a URL expira em 24 h.
Ignore waiting_message: true (ou mostre “carregando”); o evento definitivo chega em seguida com o mesmo message_id.
Para não receber tipos que não usa (áudio, documentos, grupos), use os filtros em vez de descartar no seu lado.

Começar

Autenticação e segurança

Webhooks

Guias

Migrando do z-api

Integrações

Partner

Referências

Webhook received

Envelope

Conteúdo por tipo

Mensagens enviadas por você

Grupos

Dicas

​Envelope

​Conteúdo por tipo

​Mensagens enviadas por você

​Grupos

​Dicas

Envelope

Conteúdo por tipo

Mensagens enviadas por você

Grupos

Dicas