Como integrar a API oficial do WhatsApp com o n8n na prática

Se você chegou aqui querendo saber como integrar o WhatsApp com o n8n, a resposta curta é: você não conecta o n8n direto na Meta. Você conecta o n8n à covercut, que já é a BSP oficial cuidando do app, do token e da conta na Meta. O n8n vira a camada que orquestra tudo — recebe as mensagens que chegam via webhook e dispara respostas chamando nossa API. Nada de criar app no painel de desenvolvedor, nada de gerenciar token do WhatsApp.

Vou mostrar o fluxo real, o que costuma travar e os JSON que você vai colar. Nada de teoria solta.

O que você precisa antes de abrir o n8n

Antes de arrastar qualquer node, você precisa de um número já conectado na covercut. Isso significa ter uma WhatsApp Business Account (WABA) ativa através do nosso Embedded Signup, com o número aprovado. Na prática, quando um cliente nos procura reclamando que o n8n não recebe nada, quase sempre o problema não está no n8n: está na URL de webhook cadastrada errada no nosso painel, ou na chave de API trocada.

O número pode ser conectado em modo de coexistência, ou seja, você continua usando o app WhatsApp Business no celular e ainda assim recebe e envia pela API no n8n, no mesmo número, sem apagar o histórico. Isso muda bastante o cenário de automação, porque atendimento humano no celular e automação no n8n passam a conviver — e você consegue diferenciar quem respondeu (celular ou API) em cada evento.

Você vai precisar de três coisas, todas do dashboard da covercut (não da Meta):

• X-API-Key e X-API-Secret: suas credenciais de API, em Configurações > API.
• Phone Number ID: só necessário se você tiver mais de um número conectado na mesma conta (veja em /api/v1/numbers/list). Com um único número, a API usa ele automaticamente.
• Webhook Secret: gerado automaticamente na primeira vez que você configura um webhook — usado só se quiser validar a assinatura das requisições.

Não existe app na Meta pra criar, nem verify token pra registrar lá, nem access token pra renovar. Isso tudo é responsabilidade da covercut, que já é parceira Meta para WhatsApp.

Parte 1: receber mensagens no n8n com webhook

Diferente de uma integração direta com a Cloud API, aqui não tem verificação hub.challenge nem payload cru da Meta pra decifrar. Você só precisa de um endpoint HTTPS público recebendo POST.

No n8n:

1. Crie um workflow novo e adicione um node Webhook.
2. HTTP Method: POST.
3. Path: algo como whatsapp-in.
4. Respond: "Immediately" (com status 200), já que não há verificação síncrona pra fazer — a covercut já validou tudo com a Meta antes de te entregar o evento.
5. Copie a Production URL do webhook.

Agora cadastre essa URL no nosso sistema. Duas formas:

Pelo painel: Configurações > Webhook, cole a URL. Ou pela API (útil se você provisiona números programaticamente):

• Method: POST
• URL: https://api.covercut.com.br/api/v1/numbers/webhook
• Headers: X-API-Key e X-API-Secret

{ "from": "123456789012345", "webhook_url": "https://seu-n8n.com/webhook/whatsapp-in" }

A partir daí, cada mensagem recebida chega no n8n já limpa, sem a bagunça de entry[]/changes[]/value[] da Meta:

{ "event": "message", "direction": "inbound", "from_number_id": "123456789012345", "contact": { "wa_id": "5511999998888", "name": "Maria" }, "message": { "id": "wamid.XXXX", "type": "text", "text": "oi" } }

Para pegar o texto e o número do remetente, você acessa {{$json.body.message.text}} e {{$json.body.contact.wa_id}}. Vale colocar um node IF logo depois do Webhook checando {{$json.body.event}} == "message" e {{$json.body.direction}} == "inbound" — porque o mesmo webhook também traz eventos de status (entregue, lido) e echo (mensagens que saíram pelo próprio número, seja pelo celular ou pela API), que você normalmente não quer tratar como nova conversa.

Se quiser validar que a chamada realmente veio da covercut, use o header X-BSP-Signature (HMAC-SHA256 com o Webhook Secret) — no n8n isso é um node Crypto (Hmac) comparando o hash de {{ JSON.stringify($json.body) }} com o header.

Parte 2: enviar mensagens do n8n para a covercut

Aqui também muda: você não chama a Graph API da Meta com um token seu. Você chama a API da covercut, que fala com a Meta por trás. No n8n, use um node HTTP Request:

• Method: POST
• URL: https://api.covercut.com.br/api/v1/messages/send
• Headers: X-API-Key: sua_chave e X-API-Secret: seu_segredo
• Body: JSON

O corpo para uma resposta de texto simples dentro da janela de conversa:

{ "to": "{{$json.body.contact.wa_id}}", "type": "text", "text": { "body": "Recebemos sua mensagem, já vou te ajudar." } }

Se você tiver mais de um número conectado, acrescente "from": "ID_DO_NUMERO" pra escolher o canal — sem isso, é usado o primeiro número da conta.

Aqui entra o detalhe que mais gera dúvida, e esse não muda com a covercut porque é regra da própria Meta: você só pode mandar texto livre assim dentro da janela de 24 horas. Depois que o cliente te envia algo, você tem 24 horas para responder o que quiser. Passou disso, sem uma nova mensagem dele, o envio de texto livre é bloqueado e você precisa de um template aprovado.

Parte 3: disparar templates aprovados

Templates (modelos de mensagem) são o que permite iniciar conversa ou responder fora da janela de 24h. Eles precisam ser aprovados pela Meta antes do envio e se dividem em marketing, utilidade e autenticação. Na covercut, o disparo usa um endpoint dedicado:

• Method: POST
• URL: https://api.covercut.com.br/api/v1/messages/template
• Headers: X-API-Key e X-API-Secret

{ "to": "5511999998888", "type": "template", "template": { "name": "confirmacao_pedido", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Maria" }, { "type": "text", "text": "#4832" } ] } ] } }

Quando um cliente nos chega com template rejeitado, na maioria das vezes é por dois motivos: o texto parece promocional mas foi cadastrado como utilidade, ou os placeholders {{1}} estão sem exemplo preenchido no cadastro. Ajuste isso antes de culpar o n8n.

Um ponto importante sobre custo, porque aparece muito nessa hora: a cobrança das mensagens é feita pela Meta, direto no cartão que o cliente cadastra na conta dele, por conversa e não por mensagem individual. A covercut não cobra por mensagem, conversa nem template. O que a covercut cobra é uma mensalidade fixa pela plataforma, conexão do número e suporte. Na coexistência, aliás, conversas iniciadas pelo próprio celular não geram esse custo.

Montando o fluxo completo

Um workflow básico de atendimento automático no n8n fica com esta espinha dorsal:

1. Webhook recebe o POST da covercut (já validado e formatado).
2. IF filtra: event == "message" e direction == "inbound"? Se não, encerra (era status ou echo).
3. Set ou Edit Fields extrai contact.wa_id e message.text para variáveis limpas.
4. Lógica de negócio: um Switch por palavra-chave, uma consulta a banco, ou uma chamada a um modelo de IA.
5. HTTP Request chama /api/v1/messages/send (ou /messages/template fora da janela de 24h) com sua X-API-Key/X-API-Secret.

Para respostas com IA, encaixe um node de LLM entre o passo 3 e o 5, jogue o texto do cliente como prompt e use a saída no text.body. Como o node Webhook já responde "Immediately" no passo 1, você não corre risco de a Meta reenviar o evento por demora — o processamento de IA pode levar o tempo que precisar depois disso.

Erros que mais aparecem no dia a dia

O que mais derruba uma integração recém-montada, na nossa experiência:

• URL de webhook desatualizada: o workflow do n8n mudou de endereço (ou foi recriado) e ninguém atualizou a URL em Configurações > Webhook.
• Chave de API de outra conta: colar X-API-Key/X-API-Secret errados retorna "número não encontrado" mesmo com a chamada estruturalmente correta — confira se são as chaves da conta certa.
• Confundir eventos: sem o filtro event == "message", seu fluxo tenta responder também a status (entregue/lido) e echo (mensagem que você mesmo enviou), o que pode gerar loop ou erro no node seguinte.
• Enviar texto fora da janela: a API retorna erro e a solução é template, não insistir no texto.
• Ignorar a qualidade do número: automação disparando muita mensagem ativa sem opt-in derruba a qualidade para amarelo ou vermelho e reduz seus limites. Colete consentimento antes de mandar mensagem ativa.

Sobre limites: existem tiers diários de conversas iniciadas pela empresa, que sobem conforme qualidade, volume e verificação da empresa no Gerenciador de Negócios. Se você planeja disparo em escala pelo n8n, respeite também o rate limit da própria API da covercut (60 req/min no plano Básico, 180 no Pro).

O próximo passo prático: monte primeiro o fluxo de recebimento e confirme que o JSON chega no n8n antes de se preocupar com envio. Um webhook recebendo mensagens já resolve metade do caminho. Se o seu número ainda não está conectado ou você quer conectá-lo em coexistência sem perder o WhatsApp do celular, fale com a covercut para fazer a conexão pelo fluxo oficial da Meta e receber as credenciais prontas para colar no n8n.

Se você quiser conhecer melhor sobre os endpoints, consulte nossa documentação.

Perguntas frequentes

Preciso criar um app na Meta para usar o n8n com o WhatsApp?

Não. Com a covercut, você nunca cria app na Meta nem mexe no painel de desenvolvedor. Você pega X-API-Key e X-API-Secret no dashboard e cadastra a URL do seu webhook n8n em Configurações > Webhook — a covercut já é parceira Meta e cuida da parte técnica com a Meta por trás.

O n8n consegue enviar mensagem a qualquer momento?

Depende. Dentro da janela de 24 horas após o cliente te enviar uma mensagem, você envia texto livre normalmente via /api/v1/messages/send. Fora dessa janela, só com um template aprovado pela Meta, via /api/v1/messages/template. Essa regra é da própria Cloud API, não muda com o BSP.

Usar o n8n com a covercut faz eu perder o WhatsApp no celular?

Não, se a conexão for em coexistência. Nesse modo o mesmo número funciona no app WhatsApp Business no celular e na API ao mesmo tempo, sem apagar histórico. Você atende manualmente pelo celular e automatiza pelo n8n em paralelo — e cada evento no webhook informa se a mensagem saiu pelo celular ou pela API.

Quanto custa enviar mensagens pelo n8n com a covercut?

As mensagens são cobradas pela Meta, direto no cartão do cliente cadastrado na conta dele, por conversa e não por mensagem. A covercut cobra apenas uma mensalidade fixa pela plataforma, conexão e suporte, e não cobra por mensagem, conversa ou template. Na coexistência, conversas iniciadas pelo celular não geram custo.

Por que meu webhook do n8n não recebe as mensagens?

Os motivos mais comuns são: a URL cadastrada em Configurações > Webhook está desatualizada ou aponta pro workflow errado, o webhook está desabilitado (enabled: false), o workflow no n8n não foi ativado (a Production URL só funciona com o workflow ativo), ou o node IF está barrando por confundir eventos de status/echo com message.