Criar conta
← Blog

·

n8n com a API oficial do WhatsApp: guia de integração

Atualizado em 25/10/2026

Para integrar o n8n com a API oficial do WhatsApp, você tem dois caminhos: usar os nós nativos WhatsApp Business Cloud (para enviar) e WhatsApp Trigger (para receber), ligados direto a um app da Meta, ou usar os nós genéricos Webhook e HTTP Request, que funcionam com a Cloud API e com qualquer provedor que repasse os webhooks da Meta. Os nós nativos são mais rápidos de configurar; o caminho genérico dá mais controle e evita a limitação de um webhook por app.

Este guia explica o que cada nó faz, quais credenciais pedem, os erros que mais travam a integração e um fluxo de exemplo que recebe mensagens e responde automaticamente.

Os nós do n8n para WhatsApp

Segundo a documentação do n8n, o nó WhatsApp Business Cloud tem estas operações:

RecursoOperações
MessageSend, Send and Wait for Response, Send Template
MediaUpload, Download, Delete

O WhatsApp Trigger inicia o fluxo a partir de eventos da conta. A página do trigger lista: Messages, Message Template Status Update, Message Template Quality Update, Template Category Update, Phone Number Quality Update, Phone Number Name Update, Account Update, Account Review Update, Business Capability Update e Security.

Duas operações merecem destaque:

  • Send and Wait for Response pausa o fluxo até a pessoa aprovar, recusar ou responder um formulário. Serve para aprovação humana, inclusive antes de um agente de IA executar uma ferramenta.
  • Operações não suportadas (marcar como lida, enviar lista interativa, gerenciar templates) podem ser feitas com o nó HTTP Request usando a mesma credencial do WhatsApp, pela opção Predefined Credential Type.

Credenciais: o que o n8n pede

O n8n usa dois tipos de credencial, conforme a página de credenciais do WhatsApp:

NóTipoCampos
WhatsApp Business CloudAPI keyAccess Token e Business Account ID (o ID da WABA)
WhatsApp TriggerOAuth2Client ID (App ID) e Client Secret (App Secret)

Pré-requisitos do lado da Meta: conta de desenvolvedor, portfólio empresarial, app do tipo empresa com o produto WhatsApp, URLs de política de privacidade e termos preenchidas e app em modo Live.

Um cuidado importante: o token gerado em WhatsApp > API Setup no painel da Meta é temporário. Se você colar esse token na credencial, o fluxo para de enviar quando ele expira. Para produção, gere um token permanente com usuário do sistema e use-o no campo Access Token.

Caminho 1: nós nativos (WhatsApp Trigger + WhatsApp Business Cloud)

O passo a passo para um fluxo de resposta automática:

  1. Crie a credencial OAuth2 com o App ID e o App Secret do seu app.
  2. Adicione o WhatsApp Trigger e marque o evento Messages.
  3. Adicione um nó IF para seguir só quando houver mensagem (o evento Messages também traz status de entrega).
  4. Adicione o WhatsApp Business Cloud com a operação Message > Send, a credencial API key, o Sender Phone Number e o destinatário vindo do trigger.
  5. Publique o fluxo.

As três armadilhas do WhatsApp Trigger

A documentação do n8n descreve limitações que explicam a maior parte dos “não chega nada”:

  • Um webhook por app. A Meta permite registrar só uma URL de webhook por app. Se o mesmo app já manda eventos para o seu CRM, o n8n vai substituir essa URL.
  • Teste x produção. Alternar entre a URL de teste e a de produção sobrescreve a URL registrada. Testar um fluxo publicado pode derrubar o tráfego de produção. O contorno sugerido é despublicar enquanto testa e publicar de novo depois.
  • Assinatura da WABA. Publicar o fluxo registra a URL, mas não inscreve o app na conta do WhatsApp (WABA). Sem essa inscrição, as mensagens nunca chegam e nenhuma execução com erro aparece. Um teste bem-sucedido no painel da Meta não confirma a inscrição.

Para conferir e corrigir a inscrição:

# Lista os apps inscritos na WABA (use o ID da WABA, não o phone_number_id)
curl "https://graph.facebook.com/v26.0/WABA_ID/subscribed_apps" \
  -H "Authorization: Bearer $TOKEN"

# Inscreve o app do token na WABA
curl -X POST "https://graph.facebook.com/v26.0/WABA_ID/subscribed_apps" \
  -H "Authorization: Bearer $TOKEN"

O token precisa da permissão whatsapp_business_management. Não faça DELETE em subscribed_apps para resolver erro de webhook: isso corta todos os eventos da WABA. Se a WABA ou o número tiverem um override_callback_uri, os eventos vão para essa outra URL; vale conferir quando mensagens somem.

Caminho 2: Webhook + HTTP Request

O nó Webhook recebe qualquer POST, e o HTTP Request chama qualquer API. Com eles, o n8n vira só mais um consumidor do webhook da Meta, no mesmo formato descrito no guia de webhooks da API do WhatsApp. Esse caminho é o indicado quando:

  • o webhook do app já é usado por outro sistema, ou você usa um provedor que entrega os eventos para várias URLs;
  • você precisa de operações que o nó nativo não tem;
  • você quer validar a assinatura, deduplicar eventos ou responder 200 antes de processar.

Configurações do nó Webhook que fazem diferença:

ConfiguraçãoValor recomendadoPor quê
HTTP MethodPOSTOs eventos chegam por POST
RespondImmediatelyDevolve 200 na hora e evita reenvios da origem enquanto o fluxo roda
AuthenticationHeader Auth, quando a origem permitirImpede que qualquer um dispare o fluxo
IP(s) AllowlistOpcionalRestringe quem pode chamar a URL

O tamanho máximo de payload do Webhook é 16 MB por padrão (em instâncias self-hosted, ajustável com N8N_PAYLOAD_SIZE_MAX), acima dos 3 MB que a Meta indica para os payloads de webhook.

Se você integra direto com a Meta, a URL também precisa responder à verificação por GET: crie um segundo nó Webhook no mesmo caminho com método GET e responda com um nó Respond to Webhook devolvendo {{ $json.query["hub.challenge"] }} depois de conferir o hub.verify_token.

Lembre também da URL de produção: a URL de teste só funciona enquanto o editor está “escutando”. A URL que vai para a Meta ou para o provedor é a de produção, ativa quando o fluxo está publicado.

Exemplo de fluxo: responder mensagens recebidas

O fluxo abaixo recebe o evento, separa mensagens de status, responde com texto e, para mensagens fora do horário, avisa quando o atendimento volta.

Nó 1: Webhook (POST, Respond: Immediately).

Nó 2: Code (modo Run Once for All Items), que transforma o evento da Meta em uma lista de mensagens:

const saida = [];
for (const item of $input.all()) {
  const evento = item.json.body ?? item.json;
  for (const entry of evento.entry ?? []) {
    for (const change of entry.changes ?? []) {
      const v = change.value ?? {};
      for (const msg of v.messages ?? []) {
        saida.push({
          json: {
            phone_number_id: v.metadata?.phone_number_id,
            de: msg.from,
            nome: v.contacts?.[0]?.profile?.name ?? '',
            wamid: msg.id,
            tipo: msg.type,
            texto: msg.text?.body ?? msg.interactive?.button_reply?.title ?? '',
          },
        });
      }
    }
  }
}
return saida; // eventos só com status geram lista vazia e o fluxo para aqui

Nó 3: IF com a condição de horário, por exemplo {{ $now.setZone('America/Sao_Paulo').hour }} entre 8 e 18.

Nó 4: HTTP Request (POST para o endpoint de mensagens), com corpo JSON:

{
  "messaging_product": "whatsapp",
  "to": "{{ $json.de }}",
  "type": "text",
  "text": { "body": "Olá, {{ $json.nome }}! Recebemos sua mensagem e já vamos responder." }
}

Esse envio é uma mensagem livre e só funciona porque o cliente acabou de escrever, abrindo a janela de 24 horas. Para falar com quem não escreveu, use a operação Send Template ou um corpo com "type": "template".

A partir daqui, o fluxo pode gravar o contato num CRM, mandar o texto para um agente de IA ou abrir um chamado. Para fluxos de conversa com menus e botões, veja também Typebot com a API oficial e automações com Make e Zapier.

Como fazer com a Vectalk

Com a Vectalk, use o caminho 2. O WhatsApp Trigger nativo depende de um app da Meta seu; na Vectalk, os eventos chegam no mesmo formato da Meta pela URL que você registrar, e você pode ter várias URLs por número, então o n8n não disputa o webhook com outros sistemas.

  1. Publique o fluxo e copie a URL de produção do nó Webhook.
  2. Registre a URL na Vectalk:
curl -X POST https://apis.vectalk.com.br/api/webhooks \
  -H "Authorization: Bearer $VECTALK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "SEU_INSTANCE_ID",
    "url": "https://seu-n8n.exemplo.com.br/webhook/whatsapp",
    "name": "n8n"
  }'
  1. No HTTP Request, use POST https://apis.vectalk.com.br/api/messages e uma credencial Header Auth com nome Authorization e valor Bearer SEU_TOKEN. Com token de instância, o número é resolvido automaticamente; com token de organização, inclua phone_number_id no corpo (o Code node do exemplo já extrai esse campo).
  2. Responda 200 em menos de 20 segundos; com Respond: Immediately, o n8n faz isso por você.

As rotas estão na documentação de webhooks e de envio de texto. O custo das mensagens vem na fatura da Vectalk, sem cartão na Meta. Crie sua conta em apps.vectalk.com.br/register. Para entender a plataforma da Meta como um todo, veja o guia da API oficial do WhatsApp.

Boas práticas para fluxos de WhatsApp no n8n

  • Deduplique pelo wamid. A origem pode reenviar o mesmo evento. Guarde os IDs processados (num banco ou no Redis) e descarte repetidos antes de responder.
  • Trate status em outro fluxo. Eventos de sent, delivered, read e failed chegam na mesma URL. Separar o processamento evita respostas duplicadas e facilita relatórios; veja status de mensagem via webhook.
  • Não confie em ordem. Duas mensagens seguidas do cliente podem gerar execuções paralelas. Se a ordem importa, use uma fila.
  • Guarde credenciais no n8n. Nunca coloque o token no corpo de um nó Code ou em texto fixo do HTTP Request.
  • Monitore erros. Configure um Error Workflow para avisar o time quando um envio falhar, com o código de erro da Meta (a lista está em erros da API do WhatsApp).

Perguntas frequentes

O n8n tem nó oficial para a API do WhatsApp?

Sim. O n8n tem o nó WhatsApp Business Cloud (envio de mensagens, templates e mídia) e o WhatsApp Trigger (eventos da conta), ambos ligados à Cloud API da Meta.

Posso usar o n8n com WhatsApp via QR Code?

O n8n não tem nó nativo para isso. Integrações por QR Code dependem de APIs não oficiais, que emulam o WhatsApp Web e contrariam os Termos de Serviço do WhatsApp. Veja API oficial x não oficial.

Por que meu WhatsApp Trigger não recebe mensagens?

As causas mais comuns são o app não estar inscrito na WABA (subscribed_apps), a URL de teste ter sobrescrito a de produção ou outro sistema ter registrado a própria URL no mesmo app. A seção sobre o trigger acima mostra como conferir.

Dá para enviar template pelo n8n?

Sim, com a operação Send Template do nó WhatsApp Business Cloud ou com um HTTP Request com "type": "template". O erro “Bad request – please check your parameters” costuma indicar parâmetros fora da ordem ou do tipo esperado pelo template.

Preciso de n8n self-hosted?

Não. Os nós funcionam no n8n Cloud e no self-hosted. No self-hosted, a URL do n8n precisa ser pública e HTTPS para receber os webhooks.

Fontes oficiais consultadas em 25/10/2026: n8n: WhatsApp Business Cloud node, n8n: WhatsApp Trigger node, n8n: WhatsApp credentials, n8n: Webhook node, n8n: WhatsApp node common issues, Meta: Webhooks da Cloud API, Documentação da Vectalk: Webhooks.

Integre o WhatsApp oficial ao seu sistema

A Vectalk entrega a Cloud API da Meta com os mesmos payloads e webhooks, um token para todas as contas e documentação completa.

Criar conta grátis
Ler a documentação