API oficial do WhatsApp no n8n: como receber e responder mensagens

O que você precisa antes de conectar o WhatsApp oficial ao n8n?

Quatro coisas: uma conta do Facebook com acesso ao portfólio empresarial da empresa (dá para criar um durante a conexão), o número que vai usar, um n8n acessível pela internet com endereço https e uma conta no Omnique. Você não precisa criar app na Meta, gerar token permanente nem configurar webhook no painel de desenvolvedor.

• Número: pode ser novo ou o mesmo que já está no app WhatsApp Business do celular. No segundo caso a conexão usa a coexistência e o app continua funcionando. Os detalhes estão em coexistência: app e API no mesmo número.
• n8n: n8n Cloud ou auto-hospedado, tanto faz. O que importa é a URL do nó Webhook começar com https e responder pela internet. Os quatro fluxos prontos pedem o n8n 2.35 ou mais novo.
• Omnique: crie a conta em omnique.com.br/signup. O teste grátis dura 3 dias e libera uma instância, sem cartão.

Se você quer o mapa completo da API oficial antes de abrir o n8n, comece pelo guia da API oficial do WhatsApp.

Como conectar o número sem criar app na Meta?

Pelo Cadastro Incorporado da Meta, dentro do painel do Omnique. Em Conexões, clique em Conectar: abre a janela oficial da Meta, você faz login com o Facebook, escolhe o portfólio, a conta do WhatsApp e o número, e confirma. O app, o token e a inscrição dos webhooks na Meta ficam por conta do Omnique.

O Omnique é Provedor de Tecnologia (Tech Provider) da Meta, e é isso que permite oferecer o Cadastro Incorporado. Sem um provedor no meio, você cria o app de negócios, gera o token e configura o webhook por conta própria; a documentação do n8n avisa que a Meta classifica quem cria app de WhatsApp como Tech Provider. O que isso exige está em como virar Tech Provider da Meta, e cada tela da conexão está em API oficial do WhatsApp passo a passo.

Terminada a conexão, o número vira uma instância. Ela tem chave de API própria (começa com zpk_) e aceita um webhook de destino. É nesse webhook que entra a URL do n8n.

Como receber as mensagens do WhatsApp no nó Webhook do n8n?

Crie um nó Webhook com método POST, ligue a opção de corpo cru e responda por um nó Respond to Webhook. Copie a Production URL, cole como webhook de destino da instância no Omnique e publique o fluxo. A partir daí, cada evento do número chega nesse nó como um POST com JSON, assinado pelo Omnique.

1. No n8n, adicione um nó Webhook. Em HTTP Method, escolha POST. Em Respond, escolha a opção que usa o nó Respond to Webhook.
2. Em Options, ligue Raw Body. A assinatura é calculada sobre o corpo exatamente como saiu do Omnique; sem o corpo cru não há como conferir.
3. Copie a Production URL do nó.
4. No Omnique, abra Conexões, entre na instância e cole a URL na aba Webhook de destino. Guarde o segredo que aparece nesse momento: ele começa com whsec_ e só é mostrado ao criar ou rotacionar o webhook.
5. No n8n, clique em Publish. Volte ao Omnique e use o botão Testar na linha do webhook: ele manda um evento de teste e mostra o código HTTP que o seu n8n devolveu.

Aqui, teste e produção não brigam: quem cadastra a URL é você, no Omnique. Para depurar, cole a Test URL e volte para a Production URL quando terminar. Nada é sobrescrito do lado da Meta.

O formato do evento que chega

Todo evento tem o mesmo envelope. O objeto que a Meta mandou vem dentro de data, sob a chave do tipo do evento, junto com a identificação da instância:

A entrega também traz os headers X-Omnique-Event, X-Omnique-Delivery, X-Omnique-Attempt e X-Omnique-Signature-256. Numa expressão do n8n, o número do contato fica em {{ $json.body.data.message.from }} e o texto em {{ $json.body.data.message.text.body }}.

Como filtrar só o que é mensagem nova?

Coloque um nó IF depois da confirmação de recebimento, com três condições: event igual a message, origin igual a inbound e data.channel.type igual a whatsapp. O origin evita o erro mais comum de automação: responder ao eco da própria resposta e entrar em loop. Mídia chega com uma url pronta (por exemplo audio.url), que se baixa com um HTTP Request e a sua chave.

Como validar a assinatura do Omnique no n8n?

Com o nó Crypto. Ele calcula o HMAC SHA256 do corpo cru com o segredo whsec_ do webhook, em hexadecimal. Um nó IF compara sha256= mais esse valor com o header x-omnique-signature-256. Bateu, responda 200 e siga o fluxo. Não bateu, responda 401 e pare, porque a chamada não veio do Omnique.

1. Crie uma credencial Crypto no n8n e cole o segredo whsec_ inteiro no campo Hmac Secret.
2. Adicione o nó Crypto com a ação Hmac, tipo SHA256 e codificação hex, lendo o binário do corpo recebido.
3. No IF, compare o header x-omnique-signature-256 com sha256= seguido do resultado do Crypto.
4. No ramo verdadeiro, um Respond to Webhook com 200 logo em seguida. No falso, um Respond to Webhook com 401.

Responder 200 antes do resto do fluxo evita que a demora da planilha ou do modelo de IA vire falha de entrega. E a troca do segredo vale na hora: atualize a credencial no n8n antes de rotacionar.

Como responder a mensagem com o nó HTTP Request?

Com um POST no endpoint chat-send do Omnique, autenticado pela chave da instância no header Authorization: Bearer. O corpo leva o número do contato em to, o tipo em type e o conteúdo. A resposta traz o id da mensagem na Meta (o wamid) ou um campo error dizendo o que deu errado.

• Method: POST
• URL: https://bmsmuuzglqqoebaudcwk.supabase.co/functions/v1/chat-send
• Authentication: credencial Bearer Auth com a chave zpk_ da instância. Prefira uma chave só com a permissão send.
• Body: JSON, com os campos abaixo.

Erros de negócio voltam com HTTP 200 e um campo error no JSON, como canal_inativo ou chave_sem_permissao. Por isso o HTTP Request não fica vermelho sozinho: ponha um IF depois dele que pare o fluxo quando error vier preenchido. A lista de tipos e de códigos está na documentação do Omnique.

E se já passou a janela de 24 horas?

Até 24 horas depois da última mensagem do cliente, você responde com texto, mídia ou botões. Passou disso, a Meta só aceita template aprovado: type igual a template, com name, language (por exemplo pt_BR) e os components com as variáveis. Texto livre fora da janela volta com o erro 131047 da Meta.

Como não processar nem enviar a mesma mensagem duas vezes?

Use os dois identificadores que o Omnique já entrega. O delivery_id é igual em todas as tentativas de uma entrega: guarde e ignore o que já viu. A idempotency_key no envio faz o Omnique devolver o mesmo resultado, sem reenviar, se o fluxo chamar o chat-send de novo com a mesma chave.

Montar a idempotency_key a partir do delivery_id resolve os dois lados de uma vez. E a ordem de chegada não é garantida: um read pode chegar antes do delivered. Para ordenar, use o timestamp de dentro de data.message ou data.status, que é a hora em que a Meta registrou o evento.

O que acontece se o n8n ficar fora do ar?

O evento não se perde. Se o n8n devolver erro ou não responder, a entrega volta para a fila e o Omnique tenta de novo, com intervalos cada vez maiores. Esgotadas as tentativas, ela fica no log como falha e pode ser reenviada pelo painel enquanto o evento estiver guardado, o que dura 30 dias.

Se a falha se repetir entrega após entrega, o webhook é desativado e o painel mostra quantas falhas seguidas houve; os eventos desse intervalo ficam guardados para reenvio quando você reativar. Fila, retentativa e registro de cada entrega já existem, e nada disso precisa ser montado no fluxo. Por que a Meta às vezes atrasa eventos está no guia de webhook do WhatsApp Cloud API.

Nó oficial do WhatsApp, nó não oficial ou Omnique: qual usar no n8n?

Depende de quem cuida da camada da Meta. O nó oficial do n8n funciona, mas exige app próprio na Meta e convive com a regra de um webhook por app. Os nós de API não oficial conectam pelo QR Code e expõem o número a bloqueio. O Omnique entrega a API oficial pronta, usada com os nós nativos do n8n.

O nó WhatsApp Business Cloud e o WhatsApp Trigger são oficiais e falam com a Cloud API. Para a credencial, a documentação do n8n pede conta de desenvolvedor na Meta, portfólio empresarial, um app de negócios com o produto WhatsApp, um token de acesso e o ID da conta do WhatsApp Business. O ponto fraco é o webhook: a Meta registra um por app, e cada troca entre a URL de teste e a de produção sobrescreve a anterior. A documentação do n8n descreve esse problema, e uma issue aberta no repositório do n8n relata a Production URL do WhatsApp Trigger mudando depois de algumas horas no ar.

Os nós da comunidade para APIs não oficiais, como o da Evolution API, são populares porque não pagam a Meta por mensagem. A própria Evolution descreve a conexão Baileys como baseada no WhatsApp Web. Os Termos de Serviço do WhatsApp proíbem envio automatizado e uso não pessoal sem autorização, e há relato público de número caindo na conexão: "foi só ler o QRCode que já foram banidos". A comparação completa está em Evolution API ou API oficial do WhatsApp.

Quais fluxos prontos do n8n já existem?

São quatro, na seção Fluxos prontos para o n8n da documentação, montados só com nós nativos: Webhook, Crypto, IF, HTTP Request e Respond to Webhook. Nenhum arquivo traz chave ou segredo. Você cria as credenciais no seu n8n e importa cada fluxo pelo menu Import from File.

• Responder mensagem recebida: confere a assinatura e responde com texto toda mensagem nova do WhatsApp, usando o delivery_id como idempotency_key.
• Enviar template para uma planilha: envia um template aprovado para cada linha pendente do Google Planilhas, um contato por vez, com pausa.
• Encaminhar mensagens para Slack ou e-mail: avisa cada mensagem nova com contato, instância, hora e texto.
• Status de entrega e leitura na planilha: grava uma linha por entrega, leitura ou falha, casada pelo delivery_id para que a reentrega não duplique.

Quanto custa usar a API oficial do WhatsApp no n8n?

São duas contas separadas. O Omnique cobra por número conectado: R$ 50 por mês de 1 a 4 números, com preço menor a partir de 5. A Meta cobra por mensagem entregue, no cartão cadastrado na conta dela: no Brasil, R$ 0,035 para utilidade e autenticação e R$ 0,3217 para marketing. Na resposta dentro de 24 horas, são 1.000 grátis por número por mês e R$ 0,035 da 1.001ª em diante.

Valores da Meta pela tabela em reais vigente desde 1/10/2026, para conta faturada em BRL. O preço do Omnique é o da faixa de 1 a 4 números, consultado em 6/10/2026. A tabela completa por volume está em preços.

Quer ver o primeiro evento chegando no seu n8n hoje? Crie a conta, conecte o número pela Meta e cole a URL do Webhook na instância. O teste grátis dura 3 dias, sem cartão.