Como conectar o n8n na API oficial do WhatsApp e que número usar?
Por NumioPublicado em
O n8n se conecta à API oficial do WhatsApp por dois nós: WhatsApp Business Cloud, que envia mensagens, e WhatsApp Trigger, que recebe. O primeiro pede um token de acesso e o ID da conta do WhatsApp Business; o segundo pede o ID e a chave secreta do app da Meta. Nenhum dos dois cadastra o número: o número precisa já estar registrado na Cloud API antes de o fluxo rodar.
O número pode ser fixo ou virtual. A Meta verifica por ligação de voz, e com um número da Numio (R$ 25,90/mês, R$ 16,90/mês no anual) a ligação é atendida sozinha e o código aparece no painel. Use um número novo, e não o que a equipe usa no celular: número registrado na API sai do app do WhatsApp.
O mesmo vale pras outras ferramentas que conectam pela API oficial, como Chatwoot, Typebot, Make e Botpress: todas pedem um número já registrado e os mesmos identificadores da Meta.
O que o n8n pede pra conectar no WhatsApp?
| Nó | O que faz | O que pede | Onde achar na Meta |
|---|---|---|---|
| WhatsApp Business Cloud | Envia mensagem e template | Token de acesso e ID da conta do WhatsApp Business | Token: usuário do sistema, na conta empresarial. ID: no painel do app, em WhatsApp |
| WhatsApp Trigger | Dispara o fluxo quando chega mensagem | ID do app e chave secreta do app | Configurações básicas do app, no Meta for Developers |
- Use token de usuário do sistema, não o token temporário do painel do app, que expira em horas e derruba o fluxo no dia seguinte.
- O token precisa das permissões
whatsapp_business_messagingewhatsapp_business_management. - O WhatsApp Trigger registra o webhook no app da Meta. A URL do n8n precisa ser pública e com HTTPS; em instalação local, é preciso um túnel.
A Numio fornece o número e entrega o código de verificação. Envio de mensagens, templates, webhook, token e cobrança por mensagem são da Meta (ou do provedor oficial que você escolher). O número é fixo: não recebe SMS.
Como registrar o número e ligar no n8n? Passo a passo
1. Contrate o número
Em escolher número, escolha o DDD, pague e valide a identidade. Não ative o número no app do WhatsApp.
2. Adicione o número na conta do WhatsApp Business
No painel do app da Meta, em WhatsApp, adicione um número de telefone: informe o número com +55 e o nome de exibição.
3. Escolha a verificação por ligação
Na etapa do código, marque ligação, não SMS. A Meta liga, a Numio atende e o código de 6 dígitos aparece no painel e no e-mail. Digite o código na Meta.
4. Gere o token de usuário do sistema
Nas configurações da conta empresarial, crie um usuário do sistema, dê acesso ao app e à conta do WhatsApp Business e gere o token com as duas permissões do WhatsApp.
5. Crie as credenciais no n8n
No nó WhatsApp Business Cloud, cole o token e o ID da conta do WhatsApp Business. No WhatsApp Trigger, o ID e a chave secreta do app.
6. Escolha o número no nó e teste
O nó de envio lista os números da conta. Selecione o novo, mande um template pro seu celular e responda, pra ver o Trigger disparar.
Quem monta vários ambientes pode registrar o número por chamadas HTTP, inclusive de dentro do próprio n8n com o nó HTTP Request. As quatro chamadas estão em registrar número por API.
E nas outras ferramentas (Chatwoot, Typebot, Make, Botpress, Kommo)?
Todas as ferramentas abaixo conectam pela Cloud API oficial. Muda só o que cada uma pede; o registro do número, com o código por ligação, é o mesmo.
| Ferramenta | Como conecta na API oficial | O que pede |
|---|---|---|
| n8n | Nós WhatsApp Business Cloud e WhatsApp Trigger | Token, ID da conta do WhatsApp Business, ID e chave secreta do app |
| Chatwoot | Canal WhatsApp, provedor WhatsApp Cloud | ID do número, ID da conta do WhatsApp Business e token permanente; também tem cadastro pelo login da Meta |
| Typebot | Integração com a plataforma WhatsApp Business, usando o seu próprio app da Meta | Os dados do seu app e do número, seguindo o guia da ferramenta |
| Make | App WhatsApp Business Cloud | Login da Meta com escolha da conta; a conexão antiga pede token permanente e ID da conta |
| Botpress | Integração WhatsApp | Login da Meta, ou manual: token de verificação, token de acesso, chave secreta do app, ID do número e ID da conta |
| Kommo | Integração WhatsApp Business | Login da Meta com escolha da conta; exige número que receba SMS ou ligação |
Evolution API e Z-API aparecem muito nos tutoriais de n8n, mas são outro tipo de conexão. A diferença está em API oficial ou não oficial.
Por que o fluxo não envia ou não recebe? O que conferir
| Sintoma | Causa mais comum | O que fazer |
|---|---|---|
| Funcionou ontem, hoje dá erro de autenticação | Token temporário do painel do app, que expirou | Trocar por token de usuário do sistema |
| O número não aparece na lista do nó | Número adicionado mas não verificado, ou em outra conta do WhatsApp Business | Concluir a verificação por ligação e conferir o ID da conta na credencial |
| Envia template, mas texto livre falha | Fora da janela de 24 horas, só template aprovado é aceito | O cliente precisa ter escrito nas últimas 24 horas, ou use template |
| Só chega mensagem no seu celular de teste | App da Meta em modo de desenvolvimento | Publicar o app (modo ativo) |
| O Trigger não dispara | Webhook sem o campo messages assinado, ou URL sem HTTPS público | Reativar o fluxo e conferir a URL de produção do n8n |
| Template não é entregue a contatos novos | Limite de 250 clientes diferentes por 24 horas da conta nova | Verificar a empresa na Meta pra subir o limite |
Preciso de um número pra cada fluxo ou cliente?
Um número atende vários fluxos: o Trigger recebe tudo e o fluxo decide o caminho. O que pede número separado é o que precisa ficar isolado: homologação e produção, marcas diferentes, e cada cliente de uma agência, que deve ter o número na conta do WhatsApp Business dele.
Agência ou SaaS que entrega isso em escala pode contratar os números por API e receber o código por webhook, sem passo manual. Veja um número por cliente.
Perguntas frequentes
Sim. Os nós WhatsApp Business Cloud e WhatsApp Trigger do n8n conectam na Cloud API da Meta, que é a API oficial.
É o recomendado. Número registrado na API oficial sai do app do WhatsApp, então usar o número da equipe tira o atendimento do celular. Um número novo evita isso.
Funciona. O n8n só enxerga um número já registrado na Cloud API, e a Meta aceita número fixo e virtual verificados por ligação de voz.
Os nós de WhatsApp não. O número é adicionado e verificado no painel da Meta, ou por chamadas à Graph API, que dá pra fazer com o nó HTTP Request.
Um token de usuário do sistema, gerado na conta empresarial da Meta, com as permissões whatsapp_business_messaging e whatsapp_business_management. O token temporário do painel do app expira em horas.
Sim. O Chatwoot tem o canal WhatsApp Cloud e o Typebot se integra à plataforma WhatsApp Business com o seu próprio app da Meta. Os dois pedem um número já registrado.