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.
- No teste: Generate access token no API Setup, envie a mensagem de teste, valide webhook.
- Para desenvolvimento contínuo/produção: Business Settings → System users → criar System User.
- Assign Assets: app com Manage app + WhatsApp Business account com Manage WABA.
- Generate token com permissões: business_management, whatsapp_business_messaging, whatsapp_business_management (conforme o guia oficial).
- Guarde o token em secret do n8n/env — nunca no front nem no prompt do agente.
- Rotação: trate como credencial — alarme se a API voltar 401; não espere o cliente reclamar.
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.
- Trigger / webhook: URL pública HTTPS, Verify Token que você define, e validação do challenge da Meta.
- Envio: Phone Number ID + access token (System User) nas credenciais do nó Send / HTTP Request.
- App ID / App Secret: configuração do app Meta — não substituem o token de messaging.
- WABA ID e Phone Number ID: IDs diferentes; copie do API Setup, não invente.
- Crie a credencial de envio com o token permanente e teste um template/hello no Postman ou nó HTTP.
- Configure o WhatsApp Trigger (ou Webhook) com o mesmo app — verify token idêntico ao painel Meta.
- Só então ligue Trigger → lógica → Send. Se o send falha, debug credencial de envio; se o trigger não dispara, debug webhook/verify.
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
- Uma URL de webhook por app — trocar URL no painel derruba o fluxo antigo; não compartilhe o mesmo endpoint entre ambientes sem cuidado.
- Business Manager / portfólio correto ligado ao WABA — app órfão = token sem asset.
- Display name e perfil comercial aprovados antes de prometer marca no chat.
- Templates na categoria certa (Marketing/Utility/Authentication) — Marketing tem regras e qualidade score.
- Janela de 24h: fora dela, só template (ou o que a política atual permitir).
- Número de produção ≠ número de teste: migre com checklist, não “só trocar o ID”.
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.
Meta — WhatsApp Cloud API get started. Visão geral: Cloud API docs. n8n: docs.n8n.io. Políticas: WhatsApp Business Policy.
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.
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.
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.