API Oficial do WhatsApp Business com n8n e Chatwoot: a infraestrutura por trás

A API Oficial do WhatsApp Business, fornecida pela Meta, é a forma segura e escalável de automatizar o WhatsApp de uma empresa. Ela funciona com número verificado, templates aprovados e webhooks assinados. Também permite integrar ferramentas como n8n (automação) e Chatwoot (atendimento humano) sem violar os termos da plataforma.

O que define se a operação aguenta volume é a infraestrutura que recebe e processa esses eventos: VPS, IP fixo, TLS válido e uptime do webhook.

TL;DR: use a Cloud API da Meta e hospede n8n e Chatwoot numa VPS com IP fixo e HTTPS válido. Restrinja o token da Meta ao IP do servidor. A reputação do número depende da qualidade das mensagens; a estabilidade da operação depende do servidor.

Qual problema a API Oficial do WhatsApp resolve?

Muitas empresas começam automatizando o WhatsApp com bibliotecas que emulam o WhatsApp Web via QR code. Funciona para baixo volume. O problema aparece quando a operação cresce.

Os sintomas mais comuns em operações sem a API Oficial são:

Sessão que cai e exige reescanear o QR code;
Ausência de templates aprovados, sem regra clara de envio ativo;
Risco de restrição do número por comportamento considerado automatizado;
Nenhum SLA da Meta sobre a entrega.

A Rollin Host oferece as duas opções: a API Oficial, como provedora homologada pela Meta, e a API não-oficial, baseada em uazapi. A escolha é do cliente. Para quem precisa escalar com previsibilidade, o caminho técnico é a API Oficial.

Resumo: QR code serve para validar uma ideia, não para sustentar uma operação.

Qual a diferença entre Cloud API e On-Premises API?

A Meta teve dois modelos de API Oficial. A On-Premises API rodava em contêineres Docker na infraestrutura do próprio cliente. A Cloud API é hospedada pela Meta e acessada via Graph API.

A Meta descontinuou a On-Premises API. Projetos novos usam a Cloud API, e quem ainda operava on-premises precisou migrar.

Critério	Cloud API (Meta)	On-Premises API (descontinuada)	API não-oficial (QR code)
Quem hospeda o envio	Meta	Cliente	Cliente
Templates aprovados (HSM)	Sim	Sim	Não
Webhooks assinados (HMAC SHA-256)	Sim	Sim	Depende da lib
Manutenção de contêineres	Nenhuma	Alta	Média
Conformidade com termos da Meta	Total	Total	Não garantida
Status	Ativa	Encerrada	Varia

Na Cloud API, a mensagem sai dos servidores da Meta. O servidor da empresa cumpre outro papel: receber webhooks, processar a lógica e chamar a Graph API. É aí que a VPS entra.

Como a Rollin Host opera como provedora homologada da Meta?

Como provedora homologada (Tech Provider), a Rollin Host conduz o cliente pelo onboarding exigido pela Meta. O fluxo segue estas etapas:

Verificação da empresa no Meta Business Manager, com documentação que comprove a existência legal do negócio.
Número dedicado: o número não pode estar ativo no app WhatsApp comum. Também é possível migrar um número existente.
Aprovação do nome de exibição pela Meta.
Criação e aprovação de templates nas categorias marketing, utilidade e autenticação.
Geração do token de System User com as permissões whatsapp_business_messaging e whatsapp_business_management.
Configuração do webhook apontando para o servidor do cliente.

O ponto que costuma travar projetos é a etapa 4. A Meta só permite mensagem livre dentro da janela de 24 horas, que começa quando o cliente final envia uma mensagem. Fora dessa janela, só se envia template aprovado.

Mais detalhes sobre o produto estão na página da API do WhatsApp.

Resumo: sem template aprovado, não existe envio ativo na API Oficial.

Como integrar a API Oficial do WhatsApp com o n8n?

O n8n tem nós nativos para a Cloud API: o WhatsApp Trigger (entrada) e o WhatsApp Business Cloud (envio). A integração tem três partes.

1. Como configurar o webhook de entrada no n8n?

A Meta valida o webhook com uma requisição GET contendo hub.mode, hub.verify_token e hub.challenge. O endpoint precisa devolver o hub.challenge. Depois disso, cada evento chega por POST, com o header X-Hub-Signature-256.

Para o n8n gerar URLs de webhook corretas atrás de proxy reverso, as variáveis de ambiente precisam estar definidas:

# .env do n8n atrás de Traefik/Nginx
N8N_HOST=n8n.suaempresa.com.br
N8N_PROTOCOL=https
WEBHOOK_URL=https://n8n.suaempresa.com.br/
N8N_PROXY_HOPS=1

A Meta exige HTTPS com certificado válido. Certificado autoassinado ou expirado faz a verificação falhar. Se o endpoint passar a falhar repetidamente, a Meta reduz as tentativas de entrega e pode desativar o webhook.

2. Como enviar uma mensagem livre pelo n8n?

Dentro da janela de 24 horas, o envio é um POST para o endpoint /messages do phone_number_id:

curl -X POST "https://graph.facebook.com/${GRAPH_VERSION}/${PHONE_NUMBER_ID}/messages" \
  -H "Authorization: Bearer ${META_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5511999999999",
    "type": "text",
    "text": { "body": "Pedido recebido. Em breve retornamos." }
  }'

GRAPH_VERSION corresponde à versão vigente da Graph API indicada na documentação da Meta.

3. Como enviar um template (HSM) pelo n8n?

Fora da janela, o payload muda para type: template, referenciando o nome e o idioma aprovados:

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "confirmacao_pedido",
    "language": { "code": "pt_BR" },
    "components": [{
      "type": "body",
      "parameters": [{ "type": "text", "text": "#4821" }]
    }]
  }
}

No n8n, esse payload vai num nó HTTP Request ou no nó WhatsApp Business Cloud, com a operação "Send Template".

Resumo: entrada por webhook HTTPS, saída pela Graph API e template quando a janela fecha.

Para quem não quer montar a stack do zero, a VPS para n8n da Rollin Host já vem com n8n e Traefik pré-instalados. O provisionamento automático leva cerca de 5 minutos.

Por que o IP fixo do servidor importa para a API Oficial do WhatsApp?

Vale corrigir um mito antes. Na Cloud API, a reputação do número é medida pela Meta através do quality rating: bloqueios, denúncias e taxa de resposta dos usuários. O IP do servidor não entra diretamente nessa nota.

Mesmo assim, o IP fixo da VPS é crítico por quatro motivos técnicos.

Restrição do token por IP

O app da Meta permite configurar uma allowlist de IPs para chamadas de servidor. Com IP fixo, o token só funciona a partir da VPS. Se o token vazar num repositório ou num log, ele não serve para nada fora do servidor autorizado.

Com IP dinâmico, essa proteção é inviável.

Estabilidade do webhook

O DNS do subdomínio do webhook aponta para um IP. Se o IP muda, o webhook fica fora até o DNS propagar. Nesse intervalo, a Meta registra falhas de entrega.

Webhook instável significa mensagens de clientes que não chegam ao n8n. Isso derruba a taxa de resposta, e uma taxa de resposta baixa afeta indiretamente a experiência e a qualidade percebida.

Firewall e controle de acesso

Com IP fixo, é possível liberar acesso ao banco, ao painel do Chatwoot e ao SSH apenas para IPs conhecidos:

ufw default deny incoming
ufw allow 443/tcp
ufw allow from 203.0.113.10 to any port 22 proto tcp
ufw enable

Reputação em APIs não-oficiais

Aqui o IP pesa de verdade. Em soluções via QR code, a conexão sai do servidor do cliente. IPs compartilhados ou com histórico ruim aumentam o risco de restrição do número.

Na API Oficial, o IP fixo protege a operação. Na não-oficial, o IP fixo protege o próprio número.

As VPS da Rollin Host rodam em Frankfurt (Alemanha) e US-East (EUA), com AMD EPYC, NVMe, IP dedicado e proteção anti-DDoS L3/L4. Esse último ponto importa: um endpoint de webhook exposto na internet é alvo natural.

Quando adicionar o Chatwoot como inbox de atendimento humano?

O Chatwoot é uma plataforma open source de atendimento omnichannel com suporte nativo à WhatsApp Cloud API. Ele entra quando a automação deixa de resolver tudo sozinha.

Os sinais de que chegou a hora são:

Mais de um atendente respondendo o mesmo número;
Necessidade de handoff do bot para um humano com histórico preservado;
Exigência de métricas de atendimento (tempo de primeira resposta, resolução);
Conversas que precisam de etiquetas, notas internas e atribuição por equipe.

A arquitetura recomendada pela nossa equipe deixa o Chatwoot como dono do canal WhatsApp. Ele recebe o webhook da Meta. O n8n atua como Agent Bot via API do Chatwoot.

Na prática, a conversa nasce com status pending, e o bot no n8n responde. Quando a regra de handoff dispara, o n8n muda o status para open e a conversa cai na fila humana.

O motivo é simples: cada número aceita um único webhook configurado no app. Duplicar o destino gera conflito de estado entre bot e humano.

O passo a passo de instalação está em Instalar Chatwoot.

Self-hosting ou SaaS: qual o trade-off real?

Critério	n8n + Chatwoot self-hosted (VPS)	Ferramentas SaaS equivalentes
Controle dos dados (LGPD)	Total	Depende do contrato
IP fixo e allowlist de token	Sim	Geralmente não
Custo por volume	Fixo, pelo tamanho da VPS	Cresce por usuário ou execução
Manutenção	Sua (atualizações, backup)	Do fornecedor
Lock-in	Baixo (open source)	Médio a alto

Self-hosting exige disciplina operacional: backup do PostgreSQL do Chatwoot, atualização de imagens Docker, monitoramento do webhook. Quem não quer essa responsabilidade deve considerar o lado gerenciado.

Para atendimento com IA sem montar a stack, o Agente de IA no WhatsApp da Rollin Host roda na versão CRM Hunter, com GPT-4o mini e até 3.000 mensagens de IA por mês. A parte de estratégia de conversa e funil fica com a Agência Rollin, marca irmã do grupo.

Principais aprendizados

A Cloud API é o modelo oficial vigente. A On-Premises API foi descontinuada pela Meta.
Fora da janela de 24 horas, só templates aprovados podem ser enviados.
O IP fixo permite restringir o token da Meta ao servidor e mantém o webhook estável.
A reputação do número na API Oficial vem do quality rating, não do IP.
O Chatwoot deve ser o dono do canal quando houver atendimento humano, com o n8n como Agent Bot.

Perguntas frequentes

A API Oficial do WhatsApp funciona com o n8n?

Sim. O n8n tem os nós nativos WhatsApp Trigger e WhatsApp Business Cloud, que recebem webhooks da Meta e enviam mensagens e templates pela Graph API.

Preciso de IP fixo para usar a WhatsApp Cloud API?

A Meta não exige, mas o IP fixo é recomendado. Ele permite restringir o token ao servidor via allowlist e evita indisponibilidade do webhook por troca de IP.

Posso usar o mesmo número no app WhatsApp e na API Oficial?

Não. O número precisa estar dedicado à API. Um número existente pode ser migrado, mas deixa de funcionar no aplicativo comum.

O Chatwoot substitui o n8n?

Não. O Chatwoot é a inbox de atendimento humano. O n8n executa a lógica de automação e o bot. Os dois trabalham juntos, com o n8n conectado como Agent Bot.

A Rollin Host oferece só a API Oficial?

Não. A Rollin Host oferece a API Oficial, como provedora homologada pela Meta, e a API não-oficial via uazapi. O cliente escolhe conforme volume e requisitos.

O que acontece se o webhook ficar fora do ar?

A Meta tenta reenviar os eventos por um período limitado e reduz as tentativas se as falhas persistirem. Mensagens podem deixar de chegar ao sistema, por isso o uptime do servidor é crítico.

Quer validar a arquitetura antes de colocar o número em produção? Suba uma VPS para n8n, configure o webhook com HTTPS e IP fixo, e fale com o time comercial da Rollin Host pelo WhatsApp para iniciar o onboarding na API Oficial. Suporte 24/7 em português, com NF-e.