Wiki de Implementação

Processo de Entrada

Onboarding de Cliente

Passo a passo para subir um novo cliente no sistema (CRM + Chatwoot + IA via n8n). Siga as fases na ordem; seu progresso fica salvo neste navegador.

⏱️ ~30–45 min por cliente 🧱 6 fases + validação 🔁 Reaproveitável por cliente

🧭

Visão Geral — o modelo mental

Existem 4 comunicações em 3 lugares de configuração. Entender isso evita 90% da confusão (principalmente Automação ≠ Integrations → Webhooks).

n8n

→

Chatwoot API + Backend + Evolutionpostar mensagem, ler dados, logar resolução
SAÍDA · Form de credenciais (config1)

Chatwoot

→

Backend /api/chatwoot/webhookdetecta humano · limpa reabertura · métricas
ENTRADA · Integrations → Webhooks (payload PADRÃO)

Chatwoot

→

n8n (gatilho da IA)faz a IA responder
ENTRADA · Automação (payload body.messages[0])

⚠️

3 regras de ouro:
1. Backend e n8n são lugares diferentes (Integrations→Webhooks vs Automação) — formatos de payload diferentes, não dá pra trocar.
2. O agente da IA NUNCA é importado no CRM — é isso que separa IA de humano.
3. O "Webhook secret" do form é pro n8n→backend (log-resolution), não é o webhook do Chatwoot→backend.

📋

Ficha do Cliente

salva neste navegador

Preencha antes de começar. Esses valores são usados nas fases seguintes. Nada sai do seu navegador.

Nome do cliente

URL da instância Chatwoot *

Account ID no Chatwoot *

API Token Chatwoot (admin) *

Token do agente IA *

Backend URL

Fixo — sempre o backend GoodLeads.

Webhook secret do backend

MCP endpoint (Google Calendar)

Evolution instance

URL do webhook do n8n

💡

A URL do webhook do backend (Fase 3) é a sua Backend URL + /api/chatwoot/webhook. Preenchendo a ficha, ela aparece pronta lá embaixo.

Chatwoot — base de comunicação

1.1Conectar a inbox de WhatsApp do cliente

1.2Garantir que os agentes humanos existem e estão na inbox

1.3Criar o agente dedicado da IA

Settings → Agents → Add Agent
Nome padronizado: Assistente IA (use o mesmo em todo cliente)
E-mail dedicado · Papel: Agent
Adicionar à(s) inbox(es) que vai atender
Logado como ele: Profile Settings → Access Token → copiar (vai no Form do n8n)
NÃO adicionar a Team · NÃO importar no CRM

⚠️

Por que não importar no CRM: o backend separa IA de humano pelo sender.id. Se a IA virar usuária do CRM, ela seria vista como humano e se autodesligaria.

CRM — logado como super admin

2.1Contas → Nova Conta → nome do cliente, status active

2.2Ativar Chatwoot → URL + Account ID + API Token → Testar Conexão

Tem que ficar verde.

2.3Importar Agentes → criar usuários dos humanos (senha/role/permissões)

Pular o agente da IA na importação.

2.4Confirmar que um humano importado consegue logar

Webhook Chatwoot → Backend

Integrations → Webhooks

Liga: detecção de humano, limpeza na reabertura e métricas. Lugar: Settings → Integrations → Webhooks.

3.1Integrations → Webhooks → Adicionar novo webhook

3.2URL do Webhook

https://goodleads.mychooice.com/api/chatwoot/webhook

3.3Nome: Backend GoodLeads

3.4Marcar os eventos obrigatórios

✓ Mensagem criada (message_created)
✓ Conversa Atualizada (conversation_updated)
✓ Status de conversa alterado (conversation_status_changed)
opcionais p/ sync: conversation_created, contact_created, contact_updated

3.5Criar webhook

🔒

Não precisa de token nesse webhook — o backend identifica o cliente pelo account.id do payload.

Gatilho Chatwoot → n8n

Automação

Faz a IA responder. Lugar diferente da Fase 3: Chatwoot → Automação.

4.1Recriar as regras que enviam webhook pro n8n (apontando pra URL do n8n deste cliente)

Mensagem nova — gatilho principal da IA
Resolução — status → resolvido
Reabertura — resolvido → aberto (opcional p/ n8n; a limpeza já é feita pelo backend na Fase 3)

4.2Deixar ativas as regras que o fluxo usa

n8n — importar fluxo + credenciais

5.1Importar o JSON do fluxo (versão com circuit breaker corrigido)

Lê $json.body.custom_attributes.

5.2Preencher o Form "Credenciais e integrações" (config1)

URL Chatwoot · Account ID
API Token Chatwoot = Access Token do agente IA ⬅️ o pulo do gato
Backend URL (fixo) · Webhook secret · MCP · Evolution · Debounce 20s

5.3No node de seleção de agente, excluir a IA por nome

const onlineAgents = agents.filter(
a => a.availability_status === 'online' && !/assistente ia|bot/i.test(a.name)
);

5.4Ativar o fluxo novo · desativar versão antiga

✅

Validação — smoke do cliente

6.1Msg de teste no WhatsApp → IA responde como "Assistente IA"

Confirma token certo + ai_responded.

6.2Humano responde sem "Assumir" → IA cala na próxima

Prova a Fase 3 + agente dedicado (human_active).

6.3Humano resolve → conta como humano em "Resolução (Quem Fechou)"

6.4Reabrir (cliente manda msg depois de resolvida) → atributos limpos, IA volta

6.5Dashboard ok: IA×humano separados · Eficiência IA ≠ %IA · Backlog "Não atribuídas"

🎉

Passou nos 5? Cliente no ar com IA + atendimento humano + métricas corretas.

🔧

Troubleshooting

Sintoma	Causa provável	Fix
IA some/erra como humano	Agente da IA foi importado no CRM	Tirar do CRM (usar agente dedicado)
IA não para quando humano responde	Falta o webhook da Fase 3	Criar webhook do backend (3 eventos)
IA "se desliga sozinha"	IA postando com identidade de agente humano	Usar token do agente dedicado no Form
Reabertura não limpa atributos	Webhook sem `conversation_updated`	Marcar o evento na Fase 3
IA recebe transferência	IA num Team / sem filtro por nome	Tirar de Teams + filtro `!/assistente ia\|bot/i`
n8n não dispara	Regra de Automação ausente/inativa ou URL errada	Conferir Fase 4
n8n recebe mas quebra	Apontou n8n pra Integrations→Webhooks (formato errado)	n8n vai em Automação

➕

Em breve

Outras seções da wiki (configurações avançadas, integrações, FAQ do time…) entram aqui.