💬

WhatsApp Business API

Meta Cloud API

Guia completo para configurar a API oficial do WhatsApp Business via Meta for Developers e integrar ao N8N.

🎯

Visão Geral

O WhatsApp Business API permite enviar mensagens programáticas, receber mensagens via webhook e automatizar atendimento. A API oficial é gerenciada pela Meta (Facebook).

📤

Enviar Mensagens

Templates e texto livre

📥

Receber Mensagens

Webhooks em tempo real

🤖

Automação

Chatbots e fluxos

⚠️ Importante sobre Custos

A API do WhatsApp tem custo por conversa (não por mensagem). Conversas iniciadas pelo usuário são mais baratas que as iniciadas pela empresa. Verifique a tabela de preços da Meta.

📋

Pré-requisitos

✅ O que você precisa:

  • → Conta no Meta Business Suite (business.facebook.com)
  • → Conta de desenvolvedor Meta for Developers
  • → Número de telefone não vinculado ao WhatsApp pessoal
  • → Cartão de crédito para verificação (não é cobrado inicialmente)

🆓 Modo de Teste Gratuito:

  • → A Meta oferece um número de teste gratuito
  • → Você pode enviar para até 5 números cadastrados
  • → Perfeito para desenvolvimento e testes
  • → Não precisa de número próprio para começar
1

Criar App no Meta for Developers

1.1 Acessar o Portal de Desenvolvedores

  1. → Acesse developers.facebook.com
  2. → Faça login com sua conta Facebook (pessoal ou empresarial)
  3. → Se for primeira vez, aceite os termos de desenvolvedor

1.2 Criar Novo App

  1. 1. Clique em "My Apps" → "Create App"
  2. 2. Selecione "Business" como tipo de app
  3. 3. Nome do app: N8N WhatsApp Bot
  4. 4. Email de contato: seu email
  5. 5. Business Account: selecione ou crie uma
  6. 6. Clique em "Create App"

1.3 Adicionar Produto WhatsApp

  1. 1. Na página do app, role até "Add products to your app"
  2. 2. Encontre "WhatsApp" e clique em "Set Up"
  3. 3. Siga o wizard inicial (pode pular por enquanto)
2

Configurar WhatsApp Business

2.1 Obter Access Token Temporário (para testes)

  1. 1. No menu lateral do app, clique em "WhatsApp" → "API Setup"
  2. 2. Você verá o "Temporary access token" - copie este token
  3. 3. Este token expira em 24h - usaremos um permanente depois
// Token temporário (exemplo): EAAxxxxxxxxxx... // Válido por 24 horas // Use para testes iniciais

2.2 Obter Phone Number ID e Business Account ID

Na mesma página "API Setup", você encontrará:

Phone Number ID:

123456789012345

ID do número de teste da Meta

WhatsApp Business Account ID:

987654321098765

ID da conta business

2.3 Adicionar Números de Teste

  1. 1. Na seção "To", clique em "Manage phone number list"
  2. 2. Adicione os números que receberão mensagens de teste
  3. 3. Formato: código do país + número (ex: 5511999998888)
  4. 4. Cada número receberá um código de verificação
3

Criar Token de Acesso Permanente

⚠️ Por que Token Permanente?

O token temporário expira em 24h. Para automações em produção, você precisa de um token que não expire.

3.1 Criar System User

  1. 1. Acesse business.facebook.com
  2. 2. Vá em "Business Settings" (engrenagem no canto)
  3. 3. No menu lateral: "Users" → "System Users"
  4. 4. Clique em "Add"
  5. 5. Nome: N8N Bot
  6. 6. Role: Admin

3.2 Adicionar Assets ao System User

  1. 1. Clique no System User criado
  2. 2. Clique em "Add Assets"
  3. 3. Selecione "Apps" e escolha seu app WhatsApp
  4. 4. Marque "Full Control"
  5. 5. Clique em "Save Changes"

3.3 Gerar Token Permanente

  1. 1. Ainda na página do System User, clique em "Generate New Token"
  2. 2. Selecione o app
  3. 3. Marque as permissões necessárias:
// Permissões obrigatórias: whatsapp_business_messaging whatsapp_business_management // O token gerado NUNCA expira // GUARDE EM LOCAL SEGURO!
4

Configurar Webhook (Receber Mensagens)

4.1 Criar Webhook no N8N

  1. 1. No N8N, crie um novo workflow
  2. 2. Adicione um node Webhook
  3. 3. HTTP Method: GET e POST (ambos)
  4. 4. Path: whatsapp-webhook
  5. 5. Ative o workflow e copie a URL do webhook
// URL será algo como: https://seu-n8n.com/webhook/whatsapp-webhook // Ou se for N8N Cloud: https://xxx.app.n8n.cloud/webhook/whatsapp-webhook

4.2 Configurar Webhook na Meta

  1. 1. No app Meta, vá em "WhatsApp" → "Configuration"
  2. 2. Na seção Webhook, clique em "Edit"
  3. 3. Callback URL: cole a URL do webhook N8N
  4. 4. Verify Token: crie uma string qualquer (ex: meu_token_secreto_123)

4.3 Webhook de Verificação no N8N

O Meta envia um GET para verificar. Configure seu webhook assim:

// Node: Webhook (já criado) // Depois adicione: IF Node // Condição: Verificar se é validação {{ $json.query['hub.mode'] }} === 'subscribe' // Se TRUE: Respond to Webhook // Response Body: {{ $json.query['hub.challenge'] }} // Se FALSE: continua processando mensagem normalmente
5

Configurar Credencial no N8N

5.1 Criar Credencial WhatsApp

  1. 1. No N8N, vá em Credenciais
  2. 2. Clique em "Adicionar Credencial"
  3. 3. Pesquise: "WhatsApp Business Cloud API"

5.2 Preencher os Dados

Access Token:

Token permanente do System User

Business Account ID:

ID da conta WhatsApp Business

📋

Exemplos Práticos no N8N

📤 Enviar Template (primeira mensagem)

// Node: WhatsApp Business Cloud // Operation: Send Message Phone Number ID: 123456789012345 Recipient Phone: 5511999998888 Message Type: Template Template Name: hello_world Language Code: pt_BR

⚠️ Primeira mensagem DEVE ser template aprovado

💬 Responder com Texto (após contato)

// Node: WhatsApp Business Cloud // Operation: Send Message Message Type: Text Text Body: Olá {{ $json.nome }}! Recebemos sua mensagem. Em breve retornaremos.

✅ Texto livre só dentro de 24h após contato do cliente

📥 Processar Mensagem Recebida

// Webhook recebe: { "entry": [{ "changes": [{ "value": { "messages": [{ "from": "5511999998888", "text": { "body": "Olá!" }, "timestamp": "1234567890" }] } }] }] } // Extrair dados: {{ $json.entry[0].changes[0] .value.messages[0].text.body }}

🖼️ Enviar Imagem

// Node: WhatsApp Business Cloud // Operation: Send Message Message Type: Image Image URL: https://exemplo.com/imagem.jpg Caption: Confira nossa oferta! // Ou enviar documento: Message Type: Document Document URL: https://exemplo.com/doc.pdf Filename: proposta.pdf
📝

Templates de Mensagem

⚠️ Regra das 24 Horas

Você só pode enviar mensagens de texto livre se o cliente te contatou nas últimas 24 horas. Fora dessa janela, APENAS templates aprovados.

Criar Template

  1. 1. Acesse business.facebook.com → WhatsApp Manager
  2. 2. Vá em "Message Templates"
  3. 3. Clique em "Create Template"
  4. 4. Escolha categoria (Marketing, Utility, Authentication)
  5. 5. Escreva o template com variáveis {{1}}, {{2}}, etc.
  6. 6. Envie para aprovação (pode levar até 24h)
// Exemplo de template aprovado: Nome: confirmacao_pedido Categoria: Utility Texto: Olá {{1}}! Seu pedido #{{2}} foi confirmado. Valor: R$ {{3}} Obrigado pela preferência! // Usar no N8N: Template Name: confirmacao_pedido Component Parameters: - {{1}}: {{ $json.nome_cliente }} - {{2}}: {{ $json.numero_pedido }} - {{3}}: {{ $json.valor_total }}
🔧

Troubleshooting

❌ "Message failed to send" / Error 131030

Causa: Tentando enviar texto fora da janela de 24h.

Solução: Use um template aprovado para iniciar conversa.

❌ "Invalid phone number"

Causa: Formato incorreto do número.

Solução: Use formato internacional sem + ou espaços: 5511999998888

❌ "Recipient not in allowed list"

Causa: Número não cadastrado como tester (modo desenvolvimento).

Solução: Adicione o número na lista de teste ou vincule um número de produção.

❌ Webhook não recebe mensagens

Causa: Webhook não verificado ou campos não subscritos.

Solução: Na Meta, em Configuration → Webhook, clique em "Manage" e marque "messages" como subscribed.

WhatsApp Business Configurado!

Agora você pode enviar e receber mensagens automaticamente pelo N8N.

Próximo: Facebook & Instagram → Ver Todas as Conexões