Como integrar a API oficial do WhatsApp ao n8n, sem derrubar o número

Resposta curta: são dois nós. Para receber, um nó de webhook com método POST, cuja URL você cadastra na aba de webhooks do painel da Datafy, marcando os eventos messages e smb_message_echoes. Para enviar, um nó HTTP Request com POST em https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages, o token no cabeçalho e o corpo em JSON copiado da documentação.

E existe um terceiro nó que não é opcional, apesar de parecer: o filtro. Ligar o webhook direto no envio é a armadilha desta integração, porque cada mensagem que você envia gera eventos de status que voltam pelo mesmo webhook. Um fluxo que responde a tudo responde aos status, e isso multiplica. Nas palavras do Israel Henrique, CTO da Datafy, sobre montar o fluxo sem proteção: "isso aqui é perigoso. Não faça isso."

Principais pontos

• URL de teste contra URL de produção. A de teste só recebe enquanto você clica em escutar. "Já o de produção funciona sempre 24 horas por dia."
• Dois eventos. messages traz mensagens recebidas e status. smb_message_echoes traz o que o atendente manda pelo celular, e sem ele "as mensagens que você enviar no celular não vão chegar no web hook".
• O destinatário vem de dentro de messages, nunca de contacts nem do topo do payload. O objeto messages não existe no evento de status.
• Cada mensagem enviada gera três webhooks de status. Responder a eles é o que transforma uma resposta em uma sequência exponencial.
• A resposta do fluxo é mensagem de serviço, e só sai porque o cliente acabou de escrever. Ela não renova a janela de 24 horas.

Antes de montar o fluxo

Se você usa outra tecnologia, o mecanismo é o mesmo: "se você utiliza outra tecnologia, como um servidor mesmo, um código criado ali com uma linguagem de programação, você pode fazer da mesma forma." O n8n aqui é só a tela em que fica visível.

Passo 1: o nó de webhook

Adicione um nó de webhook e ajuste o método para POST. Sem isso nada chega. O n8n oferece duas URLs, e a diferença entre elas é a causa da dúvida mais comum desta integração:

O caminho é: copie a URL de teste, cadastre na aba de webhooks da Datafy, clique em escutar no n8n e mande uma mensagem para o número. Com o payload em mãos e as expressões escritas, volte ao painel, edite o webhook para a URL de produção e publique o fluxo. A partir daí as execuções aparecem na aba de execuções a cada mensagem nova.

Passo 2: os eventos, e por que são dois

Na mesma tela de cadastro você escolhe os eventos. Dois importam:

messages. Todas as mensagens recebidas no seu WhatsApp, e os status das mensagens que você envia. Essa segunda metade é a que cria o problema do laço, e é por isso que ela precisa estar clara desde o começo.

smb_message_echoes. As mensagens enviadas pelo celular do número conectado. Em coexistência, é o evento que faz a resposta do atendente aparecer no seu sistema.

O painel também tem um testador: escolha o evento, clique em enviar, e um evento falso daquele tipo chega na sua URL antes de existir tráfego real.

A documentação acrescenta o que o painel não mostra: toda entrega leva x-datafy-delivery-id, um UUID que serve como chave de idempotência para não processar duas vezes a mesma entrega. Com a assinatura ativada no número, vêm também x-datafy-timestamp e x-datafy-signature-256, um HMAC-SHA256 de {timestamp}.{corpo}. Para validar, use o corpo cru: parsear e reserializar muda os bytes e a assinatura não bate. E a sua URL precisa responder 200 em até 20 segundos, então responda na hora e processe de forma assíncrona. No n8n isso significa não pendurar chamadas lentas antes do retorno.

Como integrar a API oficial do WhatsApp ao n8n: envie e receba mensagensCanal DATA7 · 20 min · assistir no YouTube

Passo 3: ler o payload sem errar o campo

O payload que chega tem três blocos, e a confusão entre dois deles é o erro de estreia de quase todo mundo:

Dentro de contacts também vem o user_id. Vale guardá-lo desde já: a expectativa é que, no futuro, a Meta pare de enviar o telefone do usuário e mande só o user_id. Isso é progressivo, e a Datafy trata como expectativa, não como data marcada. O ponto prático: use o user_id como identificador único no seu sistema, lembrando que ele é a relação entre aquela pessoa e aquela conta empresarial, não uma identidade global. Como responder pelo user_id.

Passo 4: o nó HTTP Request

Se você ainda não tem o phone_number_id, pegue com o token:

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

No nó HTTP Request, o método é POST e a URL é a da Datafy. O começo é o único trecho que difere da documentação da Meta: "a única coisa que muda em relação à API da meta e a Datafy API é só a URL. A URL e o token é o que diferencia."

POST https://cloud.datafyapi.com.br/v1/{{ $json.body.entry[0].changes[0].value.metadata.phone_number_id }}/messages
Authorization: Bearer sk_live_xxx
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{{ $json.body.entry[0].changes[0].value.messages[0].from }}",
  "type": "text",
  "text": {
    "preview_url": false,
    "body": "Respondendo essa mensagem via API"
  }
}

No nó: cabeçalho Authorization com Bearer e o token colado da tela do número, corpo em JSON com a opção de usar JSON, e o to arrastado do payload. O caminho exato da expressão depende de como o seu nó de webhook entrega o corpo, então confira no payload que chegou antes de copiar.

Uma escolha que parece estética e é de segurança: o to vem de messages, não de contacts. As duas opções existem no payload e as duas têm o número certo. A diferença aparece só quando chega um status, e é exatamente aí que ela salva o seu número.

O laço, e por que ele cresce tão rápido

Quando você envia uma mensagem, a Meta devolve o resultado no mesmo webhook: três eventos por mensagem enviada, entregue e lida. O primeiro é sent, um tique. O segundo é delivered, dois tiques. O terceiro é read, quando a pessoa tem a confirmação de leitura habilitada. Quando o envio falha, vem um único evento, failed, com o motivo.

Agora junte isso a um fluxo que responde a tudo que chega:

"Se eu recebo o status da mensagem e respondo enviando uma mensagem nova, eu tô respondendo uma notificação da meta, e aí ela vai enviar para essa nova mensagem um novo status, que eu vou responder com uma mensagem que vai enviar novo status."

A descrição do crescimento é literal: "para cada um desses três web hooks ele iria enviar uma nova mensagem que iria voltar nove web hooks. E para cada um desses nove web hooks ele ia enviar mais isso vezes três, ou seja, um negócio exponencial." O resultado esperado desse volume saindo do seu número é bloqueio, e é por isso que o cuidado vem antes de publicar, não depois.

As duas proteções, e a ordem certa entre elas

Proteção acidental: ler de dentro de messages. O evento de status não tem o campo messages. Quando ele chega, a expressão não acha o remetente e o passo dá erro. O fluxo para ali em vez de responder. Foi o que aconteceu no teste de referência: três webhooks de status chegaram, três deram erro, e nenhuma mensagem saiu.

Proteção correta: um filtro. Não dependa de um erro para se proteger. Coloque um nó condicional logo depois do webhook, que só deixa seguir para o envio quando o payload tem messages. Assim o fluxo responde mensagem e ignora status, de propósito.

Vale registrar os status em algum lugar em vez de descartar: é do failed que você descobre por que uma mensagem não chegou.

O que a documentação acrescenta: a resposta do fluxo é mensagem de serviço

O fluxo acima funciona por um motivo que não está em nenhum nó: o cliente acabou de escrever. Isso abre a janela de 24 horas, e dentro dela você responde com mensagem livre, texto, imagem, áudio, botão ou lista, sem template aprovado.

Três consequências que o seu fluxo tem que respeitar:

A resposta do fluxo não renova a janela. Só a mensagem do cliente renova, e o prazo passa a contar da mensagem nova dele. Automação que manda mensagem "para manter a conversa aberta" não mantém nada.

Fora da janela, a requisição pode voltar HTTP 200 com ID e falhar depois. Se o seu fluxo tem fila, retentativa ou agendamento, o envio pode sair horas depois de o cliente escrever, já fora do prazo. A proteção é guardar o horário da última mensagem recebida de cada cliente e conferir antes de enviar.

Fora da janela, só template aprovado, e enviar template não abre a janela: ela abre quando o cliente responde. Como a primeira mensagem e a falha fora da janela funcionam.

E, sobre custo, a regra vale para o fluxo igual: a Meta cobra por mensagem entregue, pela categoria e pelo país. 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 tem 1.000 mensagens de serviço grátis por mês e utilidade dentro da janela passa a ser cobrada. Referências no Brasil: R$ 0,32 marketing, R$ 0,035 utilidade e autenticação. Um fluxo que responde tudo automaticamente é justamente o que consome franquia rápido.

Limites que o seu fluxo precisa respeitar

Se o seu fluxo tem um loop de envio, trate o 429 com espera, e não com retentativa imediata. As duas camadas valem ao mesmo tempo.

Por que a IA monta o corpo da requisição para você

Como o formato é o da Cloud API, um assistente de IA já sabe montar o payload: ele herdou a documentação pública da Meta. O atalho que funciona é passar para a IA a explicação curta que abre a documentação da Datafy, "ela vai entender perfeitamente e ela vai utilizar a própria documentação da meta para te ajudar". Duas condições: confira o resultado contra a documentação, principalmente em mensagem interativa, e não deixe a IA escolher o campo de onde vem o destinatário. Essa escolha é a proteção contra o laço, e ela é sua.

Perguntas frequentes

Por que o webhook só recebe quando eu clico em escutar?

Porque você cadastrou a URL de teste. Ela só funciona com a escuta ativa. Troque pela URL de produção no painel e publique o fluxo.

Uso o nó HTTP Request ou um nó pronto de WhatsApp?

O fluxo desta página envia pelo HTTP Request, com a URL da Datafy e o corpo da documentação. Assim você usa qualquer tipo de mensagem e qualquer endpoint novo da Meta, sem depender de um nó específico.

Meu fluxo mandou várias mensagens seguidas. O que aconteceu?

Ele respondeu aos status. Coloque o filtro que só deixa passar evento com messages e confira de onde o nó de envio lê o destinatário.

De onde tiro o phone_number_id?

Da tela do número, do próprio payload do webhook, ou de GET https://cloud.datafyapi.com.br/me. Lembre que ele identifica o seu número, não o de quem escreveu.

Preciso validar a assinatura do webhook no n8n?

Não é obrigatório para o fluxo funcionar, e é recomendado quando a URL é pública. Ative a assinatura no número, guarde o secret e valide o HMAC com o corpo cru.

O que o meu fluxo deve fazer quando chega um failed?

Registrar o erro ligado ao wamid do envio e avisar você. É no failed que aparece o motivo, como mensagem de serviço fora da janela ou falha no pagamento.

Posso responder pelo user_id em vez do telefone?

Pode. O campo to dá lugar a recipient, com o user_id que vem de dentro de messages. O de fora, no topo do payload, é o que gera laço.

Resumo para a sua integração

Monte nesta ordem e você nunca publica um fluxo perigoso: nó de webhook em POST, URL de teste cadastrada, eventos marcados, primeira mensagem recebida e payload lido, nó condicional exigindo messages, nó HTTP Request com o to vindo de messages, e só então a URL de produção com o fluxo publicado.

Depois de publicar, faça um teste consciente: mande uma mensagem para o número, deixe o fluxo responder uma vez, e confira nas execuções que os três status chegaram e que nenhuma segunda resposta saiu. É esse teste que prova que o filtro está no lugar.

Leia também

• A Datafy API é um espelho da Cloud API
• A primeira mensagem: webhook, envio e a falha fora da janela
• Como ver o payload das mensagens em tempo real
• Como usar o user_id no lugar do telefone