API oficial WhatsApp no n8n: tutorial completo
Como conectar a WhatsApp Cloud API (oficial) ao n8n: app Meta, webhook, tokens, templates e fluxo mínimo — low-code, não “zero código em qualquer cenário”.
Por que isso é importante
API oficial WhatsApp n8n: Meta for Developers → app + WhatsApp → token (teste) / System User (produção) → Phone Number ID → webhook no n8n (verify + ack rápido) → templates aprovados → nós de envio. Sem Business Manager/verificação e sem credenciais duplas (Trigger vs Send) o fluxo quebra. Tutorial de plumbing da API oficial — agente de vendas é outro artigo.
O que você constrói neste fluxo
Neste tutorial da API oficial do WhatsApp no n8n você monta envio/recebimento: Cloud API da Meta + n8n (trigger webhook, credenciais, send message, templates, janela 24h). Low-code, não “zero código”; o objetivo é não queimar o número com atalho não-oficial.
Atenção
Para produção e limites maiores, o portfólio/Business da Meta precisa estar em ordem (e verificação quando a Meta exigir). No get-started da Cloud API você cria app, número de teste e envia “Hello World” sem tratar verificação completa como bloqueio absoluto do primeiro teste.
Pré-requisitos: BM, app Meta e n8n
Pré-requisitos da API oficial: conta Meta, app em developers.facebook.com com WhatsApp, Business Manager/portfólio, n8n acessível por HTTPS para webhook. No primeiro teste use o número sandbox da Cloud API; produção exige BM e token permanente (System User).
Atenção
Sandbox/teste ≠ produção. Verificação do Business e App Review entram quando você escala permissões e números reais — siga o get-started oficial da Meta antes de prometer automação em massa.
Criar app no Meta for Developers
1. Acesse developers.facebook.com e faça login
Criar app para a API oficial do WhatsApp: Meus Apps → Criar aplicativo → nome + e-mail → caso de uso adequado → adicionar produto WhatsApp. Guarde App ID/Secret; eles entram nas credenciais OAuth do n8n, não no access token de envio.
2. Vinculando o WhatsApp ao seu app
No dashboard do app criado, vá na lista de produtos, escolha WhatsApp e clique em “Configurar”. Associe sua BM já verificada à aplicação. Siga todos os prompts até visualizar opções para token, números e webhooks.
Token de acesso e número de teste
Copie o token da API oficial gerado no painel — este token será usado nas credenciais do n8n. Adicione o número de teste ou outro número real (precisa validar via SMS). Guarde ambos num local seguro: sem eles o fluxo WhatsApp n8n não autentica.
Dica prática
Sempre crie um documento compartilhável com todos os tokens, IDs e números — isso evita refazer tudo por esquecimento.
Token permanente (System User) vs token temporário
Na API oficial, a doc Meta Cloud API Get Started (atualizada Jun 2026) é explícita: o token temporário do painel serve para hello_world/teste e expira rápido — não é token de produção.
BM nuance (Agent 8)
Hello World / sandbox não exige verificação completa de BM como gate. Verificação e display name entram quando você escala para número/cliente real — não misture os dois estágios.
Primeiro envio pelo painel da Cloud API
Utilize o formulário de envio de mensagem do próprio painel do Facebook Developers para disparar uma mensagem teste (“Hello, World!”). Confirme o recebimento no seu WhatsApp para validar que tudo está correto antes de seguir.
Templates: criar e aprovar modelos
A API oficial exige que qualquer mensagem proativa passe por um template validado. Acesse “Modelos” no painel do WhatsApp, clique em “Criar Modelo” e siga: defina o tipo (Marketing, Utilidade, Autenticação), insira variáveis, configure idioma, conteúdo e botões CTA, e envie para análise.
Alerta
Nunca tente disparar mensagem fora de template aprovado: sua conta pode ser limitada e o WhatsApp recusa o envio.
Janela de 24h e fluxo de sessão
Depois que seu modelo for aprovado, faça o teste completo: dispare a mensagem proativa e responda no WhatsApp para testar a janela de 24 horas de reengajamento (você pode enviar textos livres nesse período).
Validar disparos com Postman
Cole seus tokens e números no Postman, configure método POST para endpoint da Cloud API, adicione seu modelo/mensagem e envie. Analise o retorno HTTP para garantir status 200. Isso valida toda a trilha da infraestrutura antes de ir ao N8n.
Atenção
Cuidado ao expor seu access token ou ID da BM em repositórios ou fóruns — mantenha tudo privado e seguro.
Automatizar no n8n: primeiros nós
Abra seu N8n e crie novo workflow. O começo sempre será um nó trigger, normalmente do tipo Webhook ou WhatsApp (se disponível). Sculpe a automação para capturar ou enviar as mensagens conforme seu gatilho.
Webhook de recebimento no n8n
Pegue a URL do webhook criado no N8n e insira na configuração do seu app no Facebook Developers, em “Configurar webhook”. Defina um token de verificação simples (ex: 123) para testar a conexão. Salve e verifique se o teste retorna “OK” com payload real.
Credenciais WhatsApp no n8n
No N8n, crie nova credencial do tipo Oauth ou HTTP Basic, informando Client ID, Client Secret gerados em “Configurações Básico” do app, além do token copiado antes. Salve, nomeie e teste a credencial até aparecer mensagem de sucesso.
Dica técnica
Nunca use credenciais compartilhadas — sempre registre cada workflow com sua própria identidade e acesso seguro.
Credenciais duplas: Trigger OAuth vs envio (Send API)
No n8n quase sempre existem duas preocupações distintas: receber (webhook/trigger) e enviar (Graph API). Misturar App secret, verify token e access token no campo errado é o erro clássico dos tutoriais.
Enviar mensagem via n8n
Adicione nó “Send Message” no workflow, referencie a credencial criada, insira o Business Account ID (disponível no painel WhastApp do Facebook) e o número de destino. Personalize o corpo da mensagem para experimentar diferentes templates.
Debug: problemas comuns no workflow
Se o disparo falhar, verifique status HTTP no N8n, revise tokens, IDs, verifique respostas de erro. Confirme que os webhooks ainda estão ativos e as mensagens usadas correspondem a um modelo já aprovado.
Alerta final
Se sua BM perder a verificação ou as credenciais expirarem, todo envio será bloqueado. Fique atento à renovação periódica dos tokens.
Pegadinhas de produção: um webhook, BM e display name
Tutorial “funciona no teste” e quebra no primeiro cliente quando faltam estes itens:
Antes de ir a produção
Cannibalization
Esta página é plumbing Meta + n8n. Narrativa de agente de vendas/handoff → artigo “agente WhatsApp IA”.
Escalar com cuidado (templates e filas)
Escalar com cuidado: templates aprovados, fila, um webhook estável e display name/BM corretos. Campanha sem template ou com token expirado é o caminho mais rápido para falha em produção.
Próximos passos depois do fluxo mínimo
Depois do fluxo mínimo: System User token, templates Utility/Marketing, dual credentials no n8n e monitoramento de erro HTTP. Só então ligue CRM ou agente de vendas.
Fontes
Revisão em agosto de 2026 (API comercial Meta). Templates, janela de 24h e verificação de Business Manager seguem a Cloud API. Hello World / sandbox não exige o mesmo gate de produção. n8n é low-code — não “zero código” absoluto. Isto não é aconselhamento jurídico nem garantia de aprovação de BM.
<a href="https://developers.facebook.com/docs/whatsapp/cloud-api/get-started">Meta — WhatsApp Cloud API get started</a>. Visão geral: <a href="https://developers.facebook.com/docs/whatsapp/cloud-api">Cloud API docs</a>. n8n: <a href="https://docs.n8n.io">docs.n8n.io</a>. Políticas: <a href="https://www.whatsapp.com/legal/business-policy">WhatsApp Business Policy</a>.
Perguntas frequentes
Como integrar a API oficial do WhatsApp no n8n?
Crie app no Meta for Developers, configure webhook HTTPS, tokens e nós WhatsApp/HTTP no n8n. Comece no sandbox/teste antes de produção.
Preciso de Business Manager verificado para começar?
Para Hello World/sandbox, não: dá para testar com app, número de teste e token. Verificação completa entra quando for produção e escala.
Qual a diferença da API oficial vs não oficial?
Oficial traz templates, janela de 24h e compliance. Não-oficial (QR) pode banir. Negócio sério: Cloud API.
Erro comum de webhook no n8n?
URL sem HTTPS, verify token errado ou firewall. Valide o challenge da Meta primeiro; em produção, prefira token permanente de System User.
Continue explorando
Continue explorando: curso de WhatsApp API · agente WhatsApp com IA · tutorial de agente IA com n8n · Claude Opus 4 com workflows n8n · divulgar seu app de graça.