received dispara para cada mensagem que o número conectado recebe: texto, mídia, reação, voto, resposta de botão. Dispara também para eventos de chat, como alguém entrar no grupo, uma mensagem apagada ou uma 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
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
title, description, url e thumbnail_url.image, video, audio, document, sticker
image, video, audio, document, sticker
urlé assinada e expira em 24 h. Copie o arquivo para o seu storage se precisar dele depois.- Se o download/decifração falhar,
urlvem ausente edownload_errorexplica o motivo. video:seconds,is_gif.audio:ptt(voice note) eseconds.document:file_name,title,page_count.sticker:animated.view_once: truemarca mídia de visualização única. O WhatsApp não permite reencaminhar; trate como sensível.
location
location
contact e contacts
contact e contacts
contacts (array com o mesmo formato).reaction
reaction
value vazio significa que a reação foi removida.poll e poll_vote
poll e poll_vote
event e event_response
event e event_response
product e order (Business)
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)
notification (eventos de chat)
Sem conteúdo de mensagem;
notification diz o que aconteceu e notification_parameters traz os envolvidos:unsupported
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 que o número envia por fora da API: digitadas no celular, no WhatsApp Web ou em outro aparelho conectado. Chegam com from_me: true. É útil para espelhar a conversa num CRM.
O que você envia pela API não volta como received: o WhatsApp entrega a mensagem aos outros aparelhos do número, mas não ao aparelho que a enviou (o Wabox). A confirmação desses envios vem em delivery e message_status. Assim, um received com from_me: true nunca é eco de um envio seu pela API.
Status dos contatos
Por padrão,received também não inclui os status (stories) que seus contatos publicam: eles não são conversa, e um CRM que os tratasse como mensagem abriria um atendimento para quem nunca escreveu. Ligue notify_status nos filtros para recebê-los. Chegam com phone: "status@broadcast", broadcast: true e o nome de quem publicou em sender_name. A resposta de um contato ao seu status é uma mensagem privada comum e chega sempre.
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
receivedde 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 mesmomessage_id. - Para não receber tipos que não usa (áudio, documentos, grupos), use os filtros em vez de descartar no seu lado.