Como ver o payload das mensagens do WhatsApp em tempo real

Resposta curta: no painel da Datafy API existe um botão de bate-papo. Clicando nele abre um log ao vivo das mensagens enviadas e recebidas pelo número, e clicando em qualquer mensagem aparece o webhook exato daquela mensagem, "o mesmo web hook que é enviado para você". É a forma mais rápida de responder "o que chegou?" sem abrir o log do seu servidor, e é onde você vê os eventos de status de um envio pela API, um por um. Ele tem três limites que precisam estar claros antes de você confiar nele: guarda 7 dias, no máximo 100 mensagens por conversa, e não mostra mídia.

Principais pontos

• O log mostra o payload de verdade, não uma versão resumida: é o mesmo webhook entregue na sua URL.
• Uma mensagem enviada pela API aparece como vários eventos. "Quando eu envio a mensagem pela API, eu vou receber vários web hooks."
• Resposta dada fora da API chega como smb_message_echoes, o evento de mensagem enviada pelo proprietário do número.
• Mídia não é exibida. "Quando você envia imagem, vídeo, ele não mostra. Ele apenas diz que você recebeu uma imagem ou que você recebeu um vídeo."
• É log, não é caixa de entrada. Nas palavras do Israel Henrique, CTO da Datafy: "não é para ser utilizado como bate-papo ou atendimento, é apenas para logs."

Como abrir, e o que aparece na tela

No painel do número, clique em bate-papo. As conversas aparecem e as mensagens chegam ao vivo, sem recarregar a página. Cada linha é uma mensagem, e cada mensagem abre o payload que foi entregue para ela.

O primeiro teste que vale fazer é o mais simples: mande um "olá, tudo bem?" do seu celular para o número conectado. A mensagem aparece no log marcada como enviada pelo usuário, e clicando nela você vê o webhook inteiro.

Logs de mensagens em tempo real na API oficial do WhatsAppCanal DATA7 · 3 min · assistir no YouTube

Os três blocos do payload, e os dois que todo mundo confunde

Vale abrir o payload com calma na primeira vez, porque é aqui que nascem os bugs de integração:

O phone_number_id não é o número de quem escreveu, e o wa_id não é o seu número. Trocar os dois é o erro mais comum de primeira integração, e o log é justamente onde você confere isso antes de escrever a expressão que lê o campo.

Sobre o user_id: ele é a relação entre aquela pessoa e aquela conta empresarial, não uma identidade global. A mesma pessoa tem user_id diferente em cada conta empresarial com que fala. Use como chave única por conta, nunca como identidade de pessoa.

Três origens de mensagem, três eventos diferentes

Esse é o valor real do log: ele mostra, lado a lado, coisas que no seu código chegam por caminhos distintos.

Mensagem recebida. Chega pelo evento messages. É o payload dos três blocos acima.

Mensagem enviada fora da API. Uma resposta dada pelo celular ou pelo WhatsApp Web do número aparece com outro evento, o smb_message_echoes, que é a mensagem enviada pelo proprietário do número. Sem assinar esse evento, nada disso chega no seu sistema, e o atendimento feito no celular fica invisível para a sua aplicação.

Mensagem enviada pela API. Aqui não aparece um evento, aparecem vários, todos com o mesmo wamid.

A distinção entre os dois primeiros é a que mais economiza tempo de depuração, e está dita em uma frase: "depois ele vai enviar um outro hook dizendo que a mensagem foi entregue, porque enviar é diferente de entregar." O read só chega se o destinatário tiver a confirmação de leitura habilitada, então não conte com ele em toda mensagem. E quando algo dá errado "ele vai dizer também que deu um erro, que não pôde enviar mensagem".

Por que o log resolve o problema mais chato da API oficial

A resposta de um envio aceito traz só o wamid. Segundo a documentação da Datafy, isso confirma que a requisição foi recebida, não que a mensagem chegou ao cliente. E existe um caso em que essa diferença vira armadilha: enviar mensagem de serviço fora da janela de 24 horas devolve HTTP 200 com ID, igual a um envio que deu certo, e a falha só aparece depois, no evento de status.

Ou seja: a única forma de saber o que aconteceu é olhar o status. E o log é o lugar onde você olha sem precisar ter escrito nada ainda.

A regra por trás: só a mensagem do cliente abre e renova a janela de 24 horas, e a resposta da empresa não renova nada. Enviar template também não abre a janela: ela abre quando o cliente responde. Como fazer os dois envios de teste e ver a falha chegar.

Tem um efeito colateral útil nisso. A Meta cobra por mensagem entregue, pela categoria e pelo país do destinatário, e não pela requisição aceita. Então o delivered do log é, na prática, a linha que vira custo. Referências no Brasil: R$ 0,32 para marketing e R$ 0,035 para utilidade e autenticação. Até 30 de setembro de 2026, serviço e utilidade dentro da janela não são cobrados. A partir de 1º de outubro de 2026, cada número passa a ter 1.000 mensagens de serviço grátis por mês e utilidade dentro da janela passa a ser cobrada.

O que o log não mostra, e o que fazer em cada caso

Aqui está a parte que evita frustração. São quatro limites, e três deles têm solução técnica.

Mídia

Imagem, vídeo, áudio e documento não são exibidos: o log só indica que chegou. Isso não é um recorte arbitrário, é a própria natureza da mídia na API oficial. A mídia chega criptografada da Meta, e a URL que vem no payload não abre no navegador. O caminho é pegar o id da mídia no payload e chamar:

GET https://cloud.datafyapi.com.br/media/{id}
Authorization: Bearer sk_live_xxx

A resposta é uma URL pronta, hospedada em files.datafyapi.com.br, válida por 30 dias. Os prazos de mídia são três e não se confundem:

O detalhe operacional: o identificador da Meta expira em 7 dias, o mesmo prazo de retenção do log. Uma mídia que você encontrar numa entrada antiga do log pode já não ter arquivo para baixar. Como receber mídia, passo a passo.

Retenção

As mensagens ficam 7 dias e depois são deletadas. Cada conversa guarda no máximo 100 mensagens: "se chegar mais uma, ele vai excluindo as anteriores que chegaram." Nenhum dos dois limites é configurável, e não existe exportação.

A consequência é direta: o log não é o seu histórico. Se o seu produto precisa de conversa antiga, de auditoria ou de relatório, isso mora no seu banco, gravado a partir do webhook, no momento em que ele chega.

Os cabeçalhos da entrega

O log mostra o corpo do webhook. Os cabeçalhos com que ele foi entregue na sua URL não aparecem, e são três que importam: x-datafy-delivery-id, um UUID que serve como chave de idempotência; x-datafy-timestamp; e x-datafy-signature-256, o HMAC-SHA256 de {timestamp}.{corpo}, que só é enviado quando a assinatura está ativada para o número.

Duas consequências práticas. Primeira: problema de assinatura não se depura pelo log, se depura na sua URL, e sempre com o corpo cru, porque parsear e reserializar muda os bytes e a assinatura não bate. Segunda: se o seu webhook não responder 200 em até 20 segundos, o problema também não aparece aqui, porque o log registra a mensagem independentemente do que a sua URL fez com ela.

Se o evento não está assinado

O log é do número, não do seu webhook. Uma mensagem pode estar ali e não ter chegado no seu sistema simplesmente porque você não marcou aquele evento no cadastro da URL. É o caso clássico do smb_message_echoes em coexistência: a resposta do atendente aparece no log e não aparece no seu banco. Antes de procurar bug no código, confira a lista de eventos marcados. Para testar sem esperar tráfego real, o painel também tem um botão que dispara um evento falso do tipo escolhido para a sua URL.

Para que ele serve de verdade

Depurar em minutos. Ver o campo exato que chegou antes de escrever a expressão que lê esse campo. Vale especialmente no n8n, onde um caminho de expressão errado só aparece na execução. Como montar o fluxo no n8n.

Coletar payloads reais de cada tipo. Mande para o número um texto, um áudio, uma imagem, um contato, uma localização, uma resposta de botão e uma mensagem pelo celular, e copie o payload de cada uma. Serve para modelar as tabelas do seu banco antes do primeiro insert. Um atendimento construído do zero a partir desses payloads.

Confirmar por que uma mensagem não chegou. Quando um disparo tem destinatário sem entrega, o motivo está no failed daquela linha.

Provar que o filtro do seu fluxo funciona. Envie uma mensagem pela API e conte os eventos que aparecem. Se o seu fluxo respondeu a algum deles, você tem um laço de webhook para corrigir antes de crescer o volume.

Para que ele não serve

Para atendimento. Ele mostra a conversa e deixa responder, mas não é caixa de entrada: retenção curta, sem mídia, sem busca de histórico, e descartando mensagem antiga. A delimitação é do próprio time. Para atender com equipe, os caminhos são integrar a um sistema de atendimento, e o painel tem uma aba de Chatwoot que gera a URL de webhook pronta, construir o seu, ou usar o Datafy Chats, que é o produto de atendimento.

Onde olhar cada coisa

O primeiro comando, para amarrar com o código

Antes de sair do painel, vale pegar os identificadores que o seu código vai precisar, porque eles aparecem nos payloads que você acabou de ler:

GET https://cloud.datafyapi.com.br/me
Authorization: Bearer sk_live_xxx

{
  "cliente_id": "uuid-do-cliente",
  "phone_number_id": "106540352242922",
  "waba_id": "366634483210360",
  "business_id": "123456789"
}

O phone_number_id que voltar aqui é o mesmo que aparece em metadata no log. É o jeito mais rápido de confirmar que você está olhando o número certo.

Perguntas frequentes

O log mostra o mesmo payload que chega no meu webhook?

O corpo, sim: é o mesmo webhook. Os cabeçalhos da entrega, incluindo a assinatura e o identificador de entrega, não aparecem no log.

Por quanto tempo as mensagens ficam guardadas?

7 dias, com no máximo 100 mensagens por conversa. Passando disso, as mais antigas são excluídas. Não é configurável, e não há exportação.

Consigo ver a imagem que o cliente mandou?

Não pelo log. Ele só indica que chegou uma imagem ou um vídeo. Para o arquivo, pegue o id da mídia no payload e chame GET /media/{id}, que devolve uma URL válida por 30 dias.

Aparecem os status das mensagens enviadas pela API?

Aparecem, como vários eventos para o mesmo wamid: sent, delivered, read quando disponível, ou failed com o erro.

A mensagem aparece no log mas não chega no meu sistema. Por quê?

O motivo mais comum é evento não assinado no cadastro da URL, e o caso clássico é smb_message_echoes. Confira a lista de eventos antes de procurar bug no código, e use o testador de webhook do painel.

Dá para responder pelo log?

Dá, e ele não foi feito para isso. É log. Para atender com equipe, use uma caixa de entrada integrada ou o seu próprio sistema.

O log serve como histórico para o meu produto?

Não. Grave o que chega no webhook no seu banco, no momento em que chega. A retenção do log é curta de propósito.

Resumo para a sua integração

Use o bate-papo como instrumento de medição, não como fonte de dados. Ele responde rápido três perguntas que custam caro em tempo: qual é o campo exato que chegou, quantos eventos um envio gera, e por que uma mensagem não foi entregue. Para todo o resto, o seu banco.

Uma rotina que funciona bem: antes de escrever código, mande um exemplo de cada tipo de mensagem e guarde os payloads no projeto. Depois, com o fluxo pronto, volte ao log para conferir que os status chegam e que o seu fluxo não respondeu a nenhum deles.

Leia também

• A primeira mensagem: webhook, envio e a falha fora da janela
• Como integrar a API oficial do WhatsApp ao n8n
• Como receber imagem, áudio e documento na API oficial
• Como criar um atendimento de WhatsApp do zero