Pular para o conteúdo principal

Adicionar Novo Número WhatsApp

Pré-requisitos​

Antes de começar, certifique-se de ter:

  • ✅ Acesso ao Facebook Business Manager com permissões de administrador
  • ✅ Acesso ao Chatwoot como administrador e o usuário Chat no Workspace como administrador
  • ✅ Acesso ao N8N para configurar workflows
  • ✅ Um número de telefone válido para vincular ao WhatsApp Business
  • ✅ Documentos da empresa (para verificação do Facebook)

Fluxo Completo de Configuração​

1. Configurar WhatsApp Business no Facebook​

1.1. Criar App no Facebook Developers​

  1. Acesse https://developers.facebook.com/
  2. Clique em "Meus Apps" > "Criar App"
  3. Selecione o tipo: "Negócios"
  4. Preencha:
    • Nome do app: Ex: "AI Agents - Cliente X"
    • Email de contato: Seu email
    • Business Manager: Selecione ou crie um
  5. Clique em "Criar app"

1.2. Adicionar Produto WhatsApp​

  1. No painel do app, clique em "Adicionar produto"
  2. Encontre "WhatsApp" e clique em "Configurar"
  3. Aguarde a configuração automática

1.3. Adicionar Número de Telefone​

  1. Vá em WhatsApp > Introdução
  2. Clique em "Adicionar número de telefone"
  3. Escolha uma opção:
    • Usar meu próprio número: Número real da empresa
    • Gerenciar números existentes: Se já tiver números cadastrados
  4. Siga o processo de verificação:
    • Digite o número (com DDD)
    • Escolha método de verificação (SMS ou chamada)
    • Insira o código de 6 dígitos
  5. Após verificação, configure:
    • Nome de exibição: Nome que aparecerá no WhatsApp (ex: "Suporte Cliente X")
    • Categoria: Selecione a categoria da empresa
    • Descrição: Breve descrição do negócio

1.4. Adicionar Usuário INCI Brasil ao App​

🔴 ETAPA OBRIGATÓRIA: Para que o sistema funcione corretamente, é necessário adicionar o usuário técnico da INCI Brasil.

  1. No painel do Chatwoot, vá em Configurações > Agentes
  2. Clique em "Adicionar agente"
  3. Adicione o usuário:
  4. Clique em "Adicionar"

⚠️ Por que é necessário?

  • Este usuário está configurado em nós específicos do N8N
  • Sem ele, algumas funcionalidades não funcionarão corretamente
  • A permissão de Administrador é obrigatória

1.5. Criar Token Permanente​

⚠️ Importante: Tokens temporários expiram em 24 horas. Use tokens permanentes para produção.

  1. No Facebook Business Manager, vá em Configurações do Negócio
  2. Vá em Usuários > Usuários do Sistema
  3. Clique em "Adicionar" para criar um novo System User
  4. Preencha:
    • Nome: "WhatsApp API - Cliente X"
    • Função: Administrador
  5. Clique no usuário criado
  6. Vá em "Gerar novo token"
  7. Selecione o App criado anteriormente
  8. Marque as permissões necessárias:
    • whatsapp_business_management
    • whatsapp_business_messaging
    • business_management
  9. Clique em "Gerar token"
  10. ⚠️ IMPORTANTE: Copie e salve o token imediatamente (ele não será mostrado novamente)

1.6. Configurar Eventos de Webhook​

No painel do app, vá em WhatsApp > Configuração:

  1. Role até "Webhooks"

  2. Clique em "Editar"

  3. Configure a URL de retorno de chamada:

    https://n8n-queue.incibrasil.com.br/webhook/meta

  4. Configure o Token de verificação: Use uma senha segura (ex: inci_webhook_2025)

  5. Clique em "Verificar e salvar"

  6. Após salvar, clique em "Gerenciar" nos campos de webhook

  7. Inscreva-se nos seguintes eventos:

    • ✅ messages - Mensagens recebidas e enviadas
    • ✅ message_template_status_update - Status dos templates
    • ✅ message_template_quality_update - Qualidade dos templates
    • ✅ message_template_components_update - Atualizações de componentes
    • ✅ template_category_update - Categoria dos templates

⚠️ Atenção: Sem esses eventos, o sistema não receberá mensagens nem atualizações de templates.

2. Obter IDs e Tokens do Facebook​

Você precisará de 3 informações principais:

2.1. WhatsApp Business Account ID​

  1. Em WhatsApp > Configuração
  2. Copie o "ID da conta do WhatsApp Business"
    • Exemplo: 1323147952771978
    • 📝 Onde usar: N8N Switch (roteamento de mensagens)

2.2. Phone Number ID​

  1. Na mesma página, copie o "ID do número de telefone"
    • Exemplo: 109876543210987
    • 📝 Onde usar: Typing indicator (opcional)

2.3. Access Token (Permanente)​

  • Use o token gerado na etapa 1.4
  • 📝 Onde usar: Chatwoot (autenticação com API do Facebook)

3. Criar Canal no Chatwoot​

3.1. Adicionar Canal WhatsApp​

  1. Acesse o Chatwoot: https://chatwoot.zamply.com.br

  2. Vá em Settings > Inboxes > Add Inbox

  3. Selecione "WhatsApp"

  4. Escolha "WhatsApp Cloud" (API oficial)

  5. Preencha os campos:

    Informações do Canal:

    • Channel Name: Nome interno (ex: "WhatsApp Cliente X")
    • Phone Number: Número no formato internacional (+5588XXXX1234)
    • WhatsApp Business Account ID: ID obtido na etapa 2.1
    • Phone Number ID: ID obtido na etapa 2.2
    • API Key: Token permanente obtido na etapa 2.3

  6. Clique em "Create WhatsApp Channel"

3.2. Configurar Inbox​

Após criar o canal, configure a inbox:

  1. General Settings:

    • Inbox Name: Nome que aparece para os agentes
    • Enable Auto Assignment: Ativa se quiser distribuição automática

  2. Collaborators:

    • Adicione os agentes (usuários) que terão acesso
    • Adicione o bot criado para IA (se aplicável)

  3. Business Hours:

    • Configure horário de atendimento (opcional)

  4. Webhook (importante):

    • URL: https://n8n-queue.incibrasil.com.br/webhook/incoming
    • Eventos: Marque apenas message_created

3.3. Testar Conexão​

  1. Envie uma mensagem de teste para o número WhatsApp
  2. Verifique se aparece no Chatwoot
  3. Responda pelo Chatwoot
  4. Confirme que a mensagem chegou no WhatsApp

4. Configurar N8N​

4.1. Adicionar ao Workflow WhatsApp Webhook​

  1. Acesse o N8N: https://n8n-queue.incibrasil.com.br

  2. Abra o workflow "Whatsapp Webhook" (ID: MBodM5sKqcWBHJhi)

  3. Localize o nó "Switch"

  4. Clique em "Add Routing Rule"

  5. Configure:

    • Condição: 
      {{ $('Whatsapp Messages').item.json.body.entry[0].id }}
    • Operador: equals
    • Valor: WhatsApp Business Account ID (ex: 1323147952771978)
    • Nome da saída: Número formatado (ex: +55 88 2018 1234)

  6. Adicione um nó HTTP Request:

    • Nome: Chatwoot +55 88 2018 1234
    • Método: POST
    • URL: 
      https://chatwoot.zamply.com.br/webhooks/whatsapp/+5588XXXX1234
      (Use o número exato cadastrado no Chatwoot)
    • Body Type: JSON
    • JSON Body: 
      {{ $('Whatsapp Messages').item.json.body }}

  7. Conecte a saída do Switch ao novo nó HTTP Request

  8. Clique em "Save" e ative o workflow

4.2. Testar Fluxo​

  1. Envie uma mensagem de teste para o WhatsApp
  2. Verifique os logs do workflow no N8N
  3. Confirme que a mensagem foi roteada corretamente
  4. Verifique se apareceu no Chatwoot

5. Configurar Templates no Facebook​

Templates são mensagens pré-aprovadas para iniciar conversas (mensagens proativas).

5.1. Criar Template​

  1. No Facebook Business Manager, vá em Configurações do Negócio
  2. Vá em WhatsApp Manager
  3. Selecione sua conta WhatsApp Business
  4. Vá em Modelos de mensagem > Criar modelo
  5. Preencha:
    • Nome: Nome interno (sem espaços, use underscore: boas_vindas)
    • Categoria: Marketing / Utility / Authentication
    • Idioma: Portuguese (BR)
  6. Configure o conteúdo:
    • Header (opcional): Texto, imagem ou vídeo
    • Body: Corpo da mensagem (pode ter variáveis: {{1}}, {{2}})
    • Footer (opcional): Texto pequeno no rodapé
    • Buttons (opcional): Botões de ação ou resposta rápida

Exemplo:

Header: Bem-vindo!
Body: Olá {{1}}! Obrigado por entrar em contato com a {{2}}. Como podemos ajudar?
Footer: Responda a qualquer momento
Button: Falar com atendente
  1. Clique em "Enviar"
  2. Aguarde aprovação da Meta (geralmente 1-24 horas)

5.2. Sincronização Automática​

⏱️ Tempo de sincronização: Até 3 horas após aprovação

Os templates aprovados aparecerão automaticamente em:

  • ✅ Chatwoot: Em "Caixa de Mensagem > Whatsapp Templates"
  • ✅ Retool: Para uso em campanhas de disparo em massa

Não é necessário configurar nada manualmente - a sincronização é automática via API do Facebook.

6. Ativar IA (Opcional)​

Se você deseja que o bot responda automaticamente com IA:

6.1. Criar Agent no Banco de Dados​

6.2. Criar Bot no Chatwoot​

  1. Em Settings > Agents > Add Agent
  2. Após criar, vá em Profile Settings do bot
  3. Gere um Access Token
  4. Copie e salve o token

6.3. Configurar Credencial no N8N​

  1. No N8N, vá em Credentials
  2. Crie nova credencial HTTP Header Auth
  3. Preencha:
    • Name: Bot Chatwoot - Cliente X
    • Header Name: api_access_token
    • Header Value: Token do bot copiado
  4. Salve

6.4. Adicionar ao Workflow Sender​

  1. Abra o workflow "Chatwoot Messages - Sender"
  2. No nó "Verify account id" (Switch), adicione nova regra:
    • Condição: Account ID da conta no Chatwoot
    • Output: Nome da conta
  3. Adicione nó "Send message bot" usando a credencial criada
  4. Conecte ao Switch
  5. Salve e ative

Troubleshooting​

Mensagens não chegam no Chatwoot​

  1. Verifique os webhooks no Facebook:

    • URL correta: https://n8n-queue.incibrasil.com.br/webhook/meta
    • Evento messages está ativo
    • Token de verificação correto

  2. Verifique o N8N:

    • Workflow "Whatsapp Webhook" está ativo
    • Logs mostram recebimento da mensagem
    • Switch tem regra para o número novo

  3. Verifique o Chatwoot:

    • Canal está ativo
    • Token do Facebook está válido
    • IDs (Account ID e Phone Number ID) estão corretos

Templates não aparecem no Chatwoot​

  1. Aguarde até 3 horas após aprovação no Facebook
  2. Verifique se o template foi aprovado (não rejeitado)
  3. Verifique se o token do Facebook no Chatwoot está válido
  4. Force refresh na página do Chatwoot

IA não responde​

  1. Verifique o Agent no banco: 
    SELECT * FROM agent WHERE inbox_id = {SEU_INBOX_ID};
  2. Verifique se status = 1 (ativo)
  3. Verifique se o bot tem credencial correta no N8N
  4. Verifique logs do workflow "Chatwoot Messages"

Typing indicator não funciona​

  1. Verifique se o phone_number_id está sendo passado corretamente
  2. Verifique credencial do Facebook no N8N
  3. Confirme que é o Phone Number ID, não o Account ID

Próximos Passos​

Após configurar o número:

  • 📚 Personalize o prompt do Agent na tabela agent para adequar às necessidades do cliente
  • 🎯 Crie templates de mensagem no Facebook para enviar campanhas proativas
  • 🔗 Integre com APIs externas criando novos workflows de functions no N8N