FunilChat AI

O problema e as restrições

O FunilChat AI existe para responder uma mensagem de WhatsApp antes que um humano tenha tempo de abrir o aplicativo. O cliente, WA Financial Services, ajuda imigrantes brasileiros nos Estados Unidos a lidar com papelada financeira e legal: declaração de imposto, abertura de empresa, o tipo de formulário em que um prazo perdido tem consequência real. A maior parte do primeiro contato acontece pelo WhatsApp, em horários em que ninguém está numa mesa, e o fundador, Wolney, era a única pessoa respondendo. Cada minuto que um lead esperava por uma resposta era um minuto em que ele podia mandar mensagem para um concorrente em vez disso.

A resposta óbvia (colocar uma IA na frente do WhatsApp) vem com um conjunto de restrições bem menos óbvio quando o negócio é real e a IA está conversando com clientes em potencial de verdade sobre dinheiro e status de imigração de verdade.

A primeira restrição era conquistar confiança, o que pesava aqui mais do que velocidade bruta. Um cliente em potencial decidindo se entrega os próprios documentos fiscais a um desconhecido está lendo cada sinal para saber se aquela operação é competente e cuidadosa, e uma resposta um pouco errada da IA custa muito mais do que dar de ombros e tentar de novo. Se a IA e um humano respondem na mesma conversa, ou a IA continua falando depois que um humano já assumiu, esse tropeço visível causa mais dano do que uma resposta lenta jamais causaria. A troca entre IA e humano precisava ser invisível do lado do cliente e inequívoca do lado do sistema, nunca os dois respondendo, nunca nenhum dos dois.

A segunda restrição era que isso precisava funcionar para mais de um cliente sem virar mais de um sistema. A WA Financial Services era o tenant um, mas o plano desde o início era vender o mesmo produto para outras empresas pequenas de serviço que atendem o primeiro contato pelo WhatsApp. Isso descartava qualquer coisa que assumisse um negócio único e fixo (um número de WhatsApp, uma base de conhecimento, um conjunto de usuários), porque cada uma dessas suposições teria que ser desfeita depois, num sistema já no ar, para o segundo cliente pagante. Ao mesmo tempo, não havia equipe de operação nem orçamento para uma: fosse lá o que “suportar múltiplos tenants” significasse, tinha que ser algo que um desenvolvedor sozinho conseguisse rodar e entender.

A terceira restrição era peso regulatório sem orçamento regulatório. Os clientes finais aqui estão enviando o tipo de documento (SSN, equivalentes de ITIN/EIN, papelada ligada a imigração) para o qual uma fintech ou uma empresa de serviços jurídicos teria uma equipe de compliance e um orçamento de segurança dedicados. Este sistema não tem nenhum dos dois. Cada controle de segurança (autenticação multifator, revogação de sessão, cifragem de campos sensíveis, varredura de malware em documento enviado, trilha de auditoria de quem mudou o quê) teve que ser construído dentro do próprio produto, porque não havia uma camada ou equipe de segurança separada para acrescentar depois.

A quarta restrição era operacional: uma única VPS, sem ambiente de staging, e um fundador que também é o atendente humano principal respondendo o CRM de WhatsApp todo dia. Toda migration roda direto contra o banco de produção. Não existe um ensaio geral em ambiente separado onde uma mudança de schema é testada antes. A rede de segurança é revisão cuidadosa antes de rodar; não existe cópia da produção disponível para quebrar no lugar.

A última restrição era risco de fornecedor na única dependência pela qual o produto inteiro existe para conversar: o próprio WhatsApp. Não existe um caminho oficial de WhatsApp Business Cloud que caiba numa operação self-hosted e sensível a custo nesse estágio, o que significa que o sistema depende de um provedor de automação de WhatsApp cujos termos, preço ou confiabilidade estão fora do controle de qualquer um aqui. O sistema já tinha trocado de provedor uma vez. O que fosse construído a seguir tinha que partir do princípio de que isso aconteceria de novo.

Arquitetura

Uma mensagem começa no celular do cliente e chega a um módulo de WhatsApp por tenant, uma instância conectada por cliente, para que as conversas do tenant A nunca passem fisicamente pela sessão do tenant B. Dali ela passa pelo Redis, que existe por um motivo: pessoas raramente mandam uma mensagem de WhatsApp por pensamento. Um cliente de verdade manda três ou quatro mensagens curtas seguidas, e responder depois da primeira significa responder meia frase. O Redis retém e agrupa mensagens que chegam numa janela curta de tempo, para que a IA responda o pensamento inteiro em vez de interrompê-lo.

A mensagem agrupada chega a um workflow do n8n, que é o verdadeiro cérebro da camada de primeira resposta: ele contém o agente de IA (rodando sobre a OpenAI), a busca na base de conhecimento e a lógica de retomada, tudo como um único fluxo orquestrado em vez de espalhado entre serviços. Toda vez que esse workflow precisa ler ou escrever algo que pertence a um tenant específico (um cadastro de cliente, uma conversa, uma tarefa criada a partir de uma conversa), ele passa pelo backend em FastAPI em vez de tocar o Postgres diretamente.

Essa escolha de roteamento é o que torna o isolamento entre tenants real em vez de apenas pretendido. O backend seta uma variável do Postgres com escopo de sessão identificando o tenant corrente em todo request que atende, e as políticas de row-level security nas vinte e uma tabelas com escopo de tenant usam essa variável para excluir silenciosamente toda linha que não pertença a quem está chamando. Um desenvolvedor que esquece uma cláusula WHERE tenant_id = ... em algum lugar do código da aplicação não vaza dado de outro tenant, porque o próprio banco recusa a linha antes mesmo da aplicação vê-la. O único lugar onde essa fronteira não é hermética é o papel de automação sob o qual o workflow do n8n roda: ele não seta essa variável de sessão do jeito que a API seta, então roda com um bypass em vez disso, uma exceção estreita e deliberadamente visível a uma regra que, fora dela, é fail-closed, discutida como decisão própria mais abaixo.

O CRM em React é onde um atendente humano vê a mesma conversa que a IA está conduzindo, em algo próximo de tempo real. É também onde a retomada de fato acontece: um botão chamado “Assumir” liga uma flag naquela conversa, e toda conferência seguinte que o workflow de IA faz antes de mandar uma resposta vê essa flag e fica em silêncio. Nada aqui é negociado entre a IA e o humano. É um único booleano que o workflow lê antes de ter permissão para falar, o que também é o motivo de ter sido barato deixar isso à prova de falha. Trinta minutos depois da última resposta humana sem nenhuma outra ação, a flag se limpa sozinha e a IA retoma, para que uma conversa que um humano esqueceu de devolver não fique presa em silêncio indefinidamente.

Tudo que a IA ou o atendente humano tocam é escrito pelo mesmo backend, validado pelo mesmo schema e restrito pela mesma row-level security. Existe exatamente um caminho de escrita para o sistema de registro, não importa de qual lado da fronteira entre IA e humano a escrita tenha vindo.