Arquitetura — IA Chatwoot Bepex¶

1. IA ROUTER V2 (`iT5a8VV2vPF6ZpYL`)¶

Roteador central. Recebe TODOS os webhooks do Chatwoot e direciona para o workflow de IA correto.

Fluxo:

Webhook POST /v2/router
  → TIPO EVENTO (switch: message_created / conversation_status_changed / etc.)
    → status conversa aberta? (if: status == "open")
      → TIPO MSG (switch: incoming / outgoing)
        → INBOX (switch por inbox_id)
          → IAS (switch por custom_attribute "ia_responsavel_conversa")
            → PADRAO / BE (outputs)
              → losand|chapasExpandidas|chapasPerfuradas (switch final por inbox)
                → HTTP Request para webhook do workflow alvo

Nós principais (20 total): - Webhook — POST /v2/router, recebe payload completo do Chatwoot - TIPO EVENTO — Switch por event: filtra message_created e conversation_status_changed - status conversa aberta? — IF: só processa se conversation.status == "open" - TIPO MSG — Switch: separa incoming (do cliente) de outgoing (do atendente) - INBOX — Switch por inbox.id: roteia para a cadeia de IA correta - IAS — Switch por conversation.custom_attributes.ia_responsavel_conversa - losand|chapasExpandidas|chapasPerfuradas — Switch final: ![41,59,60].includes(Number(inbox_id)) decide se vai pro losand ou pro fallback

Destinos atuais: | Inboxes | Destino | Webhook URL | |---|---|---| | 41, 59, 60 | IA losand | https://n8n-hook.bepex.com.br/webhook/${WEBHOOK_IA_LOSAND_UUID} | | Outras (fallback) | BOT 1.5 DIFY DEV | https://n8n-hook.bepex.com.br/webhook/${WEBHOOK_DIFY_LEGADO_UUID} | | 62, 63, 64 | IA Prospecção | https://n8n-hook.bepex.com.br/webhook/${WEBHOOK_IA_PROSPECCAO_UUID} |

2. IA losand (`DiOL7QWomFFc9LY8`)¶

Chatbot multi-site com 3 AI Agents distintos, handoff para atendente humano, e integração WooCommerce.

Fluxo principal (87 nodes):

BOT (Webhook) 
  → FORMAT-MAIN (formata payload, URL: chat.bepex.com.br)
    → LOG (loga no console)
      → INPUTS IA (prepara inputs)
        → INBOX PERMITIDOS (verifica inbox 41/59/60)
          → Switch (SEM ETIQUETA? + labels check)
            → ADD LABEL bot-losand
              → msg sem content? / data-create / debounce check
                → IDENTIFICAR SITE (switch por inbox_id)
                  → AI Agent Losand (inbox 41)
                  → AI Agent Chapas Expandidas (inbox 59) 
                  → AI Agent Chapas Perfuradas (inbox 60)
                    → VERIFICAR HANDOFF
                      → [se handoff] Resumir Conversa → CRIAR CONVERSA BPEX (inbox 56)
                      → [se não] Call split msg Chatwoot

Padrões de design: - Debounce: sub-workflow VahE4IePbduQNU9t previne respostas duplicadas de webhooks rápidos - Label como lock: bot adiciona label bot-losand na conversa para "reivindicá-la"; ignora conversas já etiquetadas - Split de mensagem: sub-workflow Drj76ljZtSPIXj2x fatia respostas longas em múltiplas mensagens no Chatwoot - Handoff: AI Agent pode decidir transferir para humano; nesse caso, conversa é resumida e uma nova conversa é criada na inbox 56 (BPEX) - 3 prompts distintos: cada AI Agent tem prompt específico para seu site/produto - Memória Postgres: tabela n8n_chat_histories, session key = conversation_id

3. IA Prospecção (`4wLT4ni6udXSnVS9`)¶

Versão simplificada do IA losand para atendimento de representantes em prospecção. Um único AI Agent, sem handoff.

Fluxo principal (20 nodes):

BOT (Webhook)
  → FORMAT-MAIN (formata payload, URL: chat.bepex.com.br)
    → LOG
      → INPUTS IA
        → INBOX PERMITIDOS (verifica inbox 62/63/64)
          → Switch (SEM ETIQUETA? + labels check)
            → ADD LABEL bot-prospeccao
              → msg sem content? / data-create / debounce check
                → AI Agent Prospecção (prompt comercial único)
                  → Call split msg Chatwoot

Diferenças do IA losand: - 1 AI Agent em vez de 3 (prompt comercial único para todas as inboxes) - Sem handoff (sem VERIFICAR HANDOFF, sem Resumir Conversa, sem CRIAR CONVERSA BPEX) - Sem WooCommerce tools - Sem path DIFY legado - Label: bot-prospeccao (Chatwoot ID 64, cor #6366F1) em vez de bot-losand - Memória Postgres: tabela n8n_chat_histories_prospeccao (separada) - Mesmos sub-workflows: debounce + split msg

Prompt do AI Agent: Assistente comercial da Bepex focado em prospecção de representantes. Regras: max 3 parágrafos, nunca dar % exato de comissão, sempre empurrar para agendamento via Calendly (https://calendly.com/rafael-bepex/30min). Conhecimento: 30+ anos de mercado, projetos R$50k-R$800k, modelo de representação (sem vínculo, sem exclusividade), comissão sobre RB, programa de parceria com arquitetos.

Webhook path: ${WEBHOOK_IA_PROSPECCAO_UUID} (único, corrigido em 2026-05-14)

Padrões Compartilhados¶

Debounce (sub-workflow `VahE4IePbduQNU9t`)¶

Previne que múltiplos webhooks rápidos do Chatwoot (ex: mensagem + status change) gerem respostas duplicadas. Usa timestamp + conversation_id para descartar eventos redundantes.

Split Msg Chatwoot (sub-workflow `Drj76ljZtSPIXj2x`)¶

Fatia respostas longas da IA em múltiplas mensagens no Chatwoot. Respeita limite de caracteres da API e adiciona delays entre mensagens para parecer digitação humana.

Label como Lock¶

Cada workflow de IA tem sua label exclusiva. Ao receber uma mensagem: 1. Verifica se a conversa já tem a label do bot 2. Se não tem → adiciona label e processa 3. Se já tem → pula (evita reprocessamento)

Error Workflow (`GEyXmIklTx6i3QBC`)¶

Workflow de erro compartilhado. Captura exceções e notifica (provavelmente via log ou mensagem).

Convert Types Where Required (OBRIGATÓRIO em Switch nodes)¶

O Chatwoot envia inbox_id como string ("62"). Switch nodes que comparam com number (62) precisam ter a opção "Convert Types Where Required" habilitada, caso contrário a comparação falha silenciosamente. Isso causou o bug do ROUTER em 2026-05-23 — mensagens das inboxes 62/63/64 não eram roteadas. Ver historico.md para detalhes.

Ativação por tag em conversas outbound¶

O sistema distingue quem inicia a conversa: - Inbound (contato inicia) → IA ativa automaticamente - Outbound (Bepex inicia) → precisa da tag "IA atendendo" para a IA responder

Isso é crítico para o IA Prospecção, onde 100% das conversas são outbound (Bepex envia a primeira mensagem ao prospect). Sem a tag, a IA ignora as respostas dos prospects. Ver historico.md Bug 3.

Arquitetura — IA Chatwoot Bepex¶

1. IA ROUTER V2 (iT5a8VV2vPF6ZpYL)¶

2. IA losand (DiOL7QWomFFc9LY8)¶

3. IA Prospecção (4wLT4ni6udXSnVS9)¶