Chatbot de PNL para WhatsApp: exemplos de código aberto, arquitetura e um guia prático para iniciantes

Desenvolver um chatbot para WhatsApp que "entenda" (compreendendo diferentes frases, erros de digitação e intenções) não significa ficar preso a uma solução proprietária e complexa. Com plataformas de processamento de linguagem natural (PLN) de código aberto já consolidadas, você pode criar um bot para WhatsApp sobre o qual terá controle total — incluindo dados, lógica e custos — e ainda oferecer uma experiência refinada e semelhante à humana. Este guia apresenta arquiteturas de referência, opções concretas de código aberto e três exemplos completos que você pode usar em seu primeiro lançamento.

‍

Por que usar código aberto para PNL no WhatsApp?

• Controle sobre os dados e a privacidade. Mantenha os dados de treinamento, registros e modelos em seu próprio repositório/nuvem.
• Componível: Troque tokenizadores, classificadores de intenção, camadas de recuperação ou gerenciadores de diálogo sem precisar reescrever tudo.
• Transparência de custos: pague pela hospedagem/computação, não por taxas adicionais por mensagem provenientes de complementos "inteligentes".
• Velocidade da comunidade: Rasa, Haystack, spaCy e LangChain evoluem rapidamente e fornecem padrões comprovados que você pode adaptar.
  
  

‍

Bot de PNL para WhatsApp: a arquitetura mínima (e onde o código aberto se encaixa)

1. Transporte (Plataforma de Negócios do WhatsApp):
   
   • Use a plataforma WhatsApp Business da Meta (API na nuvem) como canal oficial. Ela entrega as mensagens ao seu webhook e permite que você envie respostas.
   • Você hospedará um pequeno receptor de webhook (FastAPI/Express) para verificar assinaturas, analisar JSON recebido e encaminhar um evento normalizado para o ambiente de execução do seu bot.
     
     
2. Ambiente de execução do bot (código aberto):
   
   • NLU e Gestão de Diálogos:
     
     • Rasa (de ponta a ponta: tokenizador, extração de intenção/entidade, políticas, formulários, histórias)
     • Botpress de código aberto (fluxos visuais + NLU)
     • LangChain/LangGraph (orquestração orientada a LLM caso você planeje usar modelos generativos)
       
       
   • Recuperação e conhecimento:
     
     • Haystack ou LangChain + um banco de dados vetorial (FAISS ou Chroma) para RAG (geração aumentada por recuperação).
       
       
   • Peças clássicas de PNL:
     
     • spaCy (regras, pipelines NER), Hugging Face Transformers (classificadores de intenção ajustados), fastText para linhas de base de intenção leves.
       
       
3. Estado e armazenamento:
   
   • Estado da conversa (SQLite/Postgres/Redis).
   • Índice de conteúdo (FAISS/Chroma/Weaviate).
   • Logs/métricas (Postgres + Grafana/Prometheus, ou um simples CSV/S3 se estiver em fase de prototipagem).
     
     
4. Administração e ferramentas:
   
   • Anotação e versionamento de conjuntos de dados (Label Studio + DVC/Git LFS).
   • Scripts de avaliação (pytest + métricas personalizadas para intenção F1, entidade F1 e taxa de conclusão de objetivos).
     
     

A transferência de informações é simples: WhatsApp → webhook → ambiente de execução do bot (Rasa/Botpress/LangChain) → lógica de negócios → resposta via API de envio do WhatsApp.

‍

Blocos de construção de código aberto (selecionados)

• Rasa – testado e comprovado para extração de intenções/entidades, formulários (preenchimento de campos), histórias e políticas; bom equilíbrio entre abordagens baseadas em regras e aprendizado de máquina.
• Botpress (edição de código aberto) – construtor de fluxos visuais; fácil de integrar mesmo para não desenvolvedores; ideal quando sua equipe precisa de uma tela em branco com NLU (compreensão de linguagem natural).
• spaCy – primitivas de PNL de nível de produção, modelos multilíngues, componentes personalizados para entidades baseadas em padrões.
• Haystack – pipelines RAG limpos, repositórios de documentos, recuperadores, leitores; ideal para bots de FAQ e bases de conhecimento.
• LangChain/LangGraph – agentes/ferramentas componíveis para projetos centrados em LLM; combine com um modelo aberto ou um modelo de API conforme necessário.
• FAISS / Chroma – busca vetorial leve para recuperação baseada em embeddings.
• Node-RED – uma ferramenta de baixo código para orquestrar webhooks, chamadas HTTP e tomada de decisões quando você precisa de entregas rápidas.
  
  

‍

Normalização de modelos de dados e mensagens

Os payloads do WhatsApp variam de acordo com o tipo de mensagem. Normalize-os logo no início para que sua pilha de PNL (Processamento de Linguagem Natural) veja um esquema consistente:

• carimbo de data/hora (ISO)
• do telefone (E.164)
• tipo_de_mensagem (texto | imagem | localização | áudio | documento)
• Texto (texto extraído; execute o OCR para imagens somente se realmente precisar)
• media_url (se aplicável)
• Localidade (se presente; caso contrário, usará detecção de idioma)
• session_id (estável por usuário/dia)
  
  

Mantenha as ramificações não textuais simples no início: confirme o recebimento da mídia, faça perguntas para esclarecimento e armazene as referências para revisão humana.

‍

Três exemplos de padrões de código aberto (prontos para copiar)

1) Perguntas frequentes + qualificação de leads (Rasa em primeiro lugar)

Quando escolher: Você precisa de uma classificação de intenção robusta, entidades (por exemplo, produto, cidade) e preenchimento determinístico de slots.

Fluxo:

1. Texto de entrada → Rasa NLU → intenção (consulta_de_preços, instalação_de_livro, fora_do_escopo).
2. Se houver uma consulta de preços, extraia as entidades (cidade, tipo de sistema); se estiverem ausentes, os formulários farão perguntas.
3. Recupere respostas padrão de um arquivo de conhecimento YAML/JSON ou de um gráfico RAG simples, caso o conteúdo seja extenso.
4. Encaminhar para um humano se a confiança for menor que o limite ou se o formulário expirar.
   
   

O que é ótimo: as políticas do Rasa (TED, RulePolicy) equilibram o comportamento aprendido com regras explícitas. Você pode ajustar o NLU com algumas dezenas de exemplos/intenções.

2) Perguntas e respostas baseadas em documentos (Haystack RAG)

Quando escolher: A base de conhecimento é extensa (PDFs, documentos, FAQs) e você deseja respostas fundamentadas no seu conteúdo.

Fluxo:

1. Texto de entrada → detecção de idioma → consulta de incorporação.
2. Haystack : O Retriever (por exemplo, Dense Passage Retrieval) busca as k passagens mais relevantes do FAISS/Chroma.
3. O leitor/gerador elabora uma resposta curta com citações.
4. A resposta inclui um rótulo de origem de fácil compreensão para humanos (“Guia de Instalação §2.1”).
   
   

O que é ótimo: você evita alucinações com um controle rigoroso. Você pode expandir o conteúdo sem alterar a lógica dos diálogos.

3) Triagem de serviços orientada a fluxo (regras do Botpress + spaCy)

Quando escolher: As operações dependem de fluxos de trabalho estruturados (abrir chamado, atualizar previsão de chegada, reagendar) e você deseja uma tela visual compartilhada.

Fluxo:

1. Fluxo do Botpress para ramificações de alta confiança (menu, etapas do formulário).
2. O componente personalizado spaCy marca números de pedidos, e-mails e datas.
3. O Botpress chama um servidor backend (por exemplo, /tickets/create) e envia a referência para o usuário.
4. Recorra a uma lista de respostas rápidas do tipo "Não entendi — escolha uma opção".
   
   

O que é ótimo: usuários sem conhecimento de programação podem ajustar fluxos com segurança. As regras do spaCy detectam rapidamente entidades frágeis e específicas de formato.

‍

Dados de treinamento: o que significa "suficiente"

• Intenções: Comece com 8 a 15 intenções que cubram 80% do tráfego. Cerca de 20 a 30 exemplos por intenção representam um MVP saudável.
• Entidades: Concentre-se nas entidades operacionais (cidade, ID do pedido, nível do produto). Crie algumas expressões regulares (IDs de pedidos, e-mails) para acelerar a precisão.
• Exemplos negativos: Inclua conversas fora do escopo e bate-papo informal para que a política de contingência tenha eficácia.
• Multilíngue: Se você espera uma mistura de idiomas, adicione detecção de idioma e direcione para pipelines ou modelos separados para cada idioma.
  
  

Controle as versões dos conjuntos de dados com Git + DVC. Cada compilação do modelo deve estar vinculada a um commit do conjunto de dados.

‍

Design de conversação que se adapta a diferentes escalas

• As duas ou três principais sugestões, após uma resposta alternativa ("Você quis dizer preço ou prazo de instalação?"), foram melhores do que "Desculpe, não entendi".
• Divulgação progressiva: solicite uma vaga em falta de cada vez, resuma as informações coletadas e confirme antes de tomar qualquer providência.
• Intervenção humana: Forneça uma palavra-chave como "agente" ou simplesmente detecte padrões de frustração e acione o protocolo com base no contexto da transcrição.
  
  

‍

Segurança, conformidade e especificidades do WhatsApp

• Opção de adesão e opção de cancelamento: Garanta o consentimento explícito. Faça com que o botão “PARAR” (ou uma variante local) funcione desde o primeiro dia.
• Minimização de informações pessoais identificáveis ​​(PII): Armazene apenas os campos realmente necessários (por exemplo, order_id, cidade). Mascare ou utilize hash para identificar informações sensíveis nos registros.
• Limites de taxa e novas tentativas: Implementar recuo exponencial para erros de envio; registrar códigos de resposta.
• Modelos de mensagens: Para mensagens iniciadas pela empresa fora do prazo de 24 horas, prepare modelos aprovados (requisito do WhatsApp).
• Higiene de mídia: Não baixe anexos automaticamente sem critério; faça a verificação apenas se exigido por lei.
  
  

‍

Observabilidade: meça o que importa

• Matriz de precisão e confusão de intenções: Encontre intenções semelhantes e combine ou reformule os exemplos.
• Taxa de conclusão de objetivos: Percentual de usuários que atingem um resultado comercial (reserva, criação de ingresso).
• Taxa de mensagens alternativas por tipo de mensagem: Monitore se as mensagens alternativas aumentam repentinamente para determinados idiomas ou campanhas.
• Taxa e motivos de transferência humana: Utilize categorias (faturamento, casos extremos, abuso) para priorizar o treinamento.
• Latência (p50/p90): Mantenha o tempo de resposta de ponta a ponta abaixo de 2 a 3 segundos para respostas de texto.
  
  

Comece com um painel de controle simples: sessões diárias, usuários únicos, taxa de conclusão, alternativas e média de mensagens por sessão.

‍

Guia de início rápido (roteiro de uma semana)

Dia 1 – Esqueleto

• Configurar webhook (FastAPI/Express).
• Crie um projeto Rasa (ou um espaço de trabalho Botpress).
• Conexão do WhatsApp → webhook → bot → WhatsApp.
  
  

Dia 2 – Intenções e formulários

• Defina 10 intenções e 3 entidades; adicione 20 exemplos por intenção.
• Crie um formulário (ex.: reserva: data, cidade, e-mail de contato).
• Adicione um limite de política; direcione os casos de baixa confiança para o método alternativo.
  
  

Dia 3 – Conhecimento

• Indexe de 10 a 20 documentos principais com Haystack + FAISS.
• Adicione uma intenção "/kb question" que acione o RAG com as 3 principais citações.
  
  

Dia 4 – Transição de responsabilidade humana

• Implemente um comando de escalonamento e uma caixa de entrada para agentes (inicialmente, até mesmo uma ponte compartilhada de e-mail/Slack).
• Transcrições de logs com etiquetas (“necessita de escalonamento”).
  
  

Dia 5 – Ciclo de avaliação

• Realize um teste com um pequeno grupo de participantes; colete mensagens classificadas incorretamente.
• Retreinar; comparar F1 e matriz de confusão.
  
  

Dia 6 – Modelos e trabalho fora do horário comercial

• Adicione modelos de mensagens do WhatsApp para fluxos iniciados por empresas.
• Respostas baseadas em horário (“Voltaremos às 09:00”) com uma tarefa de acompanhamento pela manhã.
  
  

Dia 7 – Endurecimento

• Adicione novas tentativas, registro de erros, verificações de integridade e uma exportação diária para o armazenamento.
• Documente o pipeline, os conjuntos de dados e as etapas de lançamento.
  
  

‍

Dicas de custo e desempenho

• Modelos: Comece com arquiteturas básicas de transformadores leves (classe DistilBERT) ou até mesmo SVM/fastText clássico para intenções, caso o orçamento seja limitado.
• Busca vetorial: o FAISS na CPU geralmente é suficiente para menos de 500 mil passagens.
• Cache: Armazene em cache respostas frequentes (por exemplo, tempos de entrega) para reduzir o processamento computacional.
• Agrupamento: Se você transmitir notificações (mensagens de modelo), agrupe as solicitações de forma responsável e respeite os limites de taxa.
  
  

‍

Armadilhas comuns (e como evitá-las)

• Excesso de intenções: Mais de 30 intenções granulares definidas muito cedo aumentam a confusão. Consolide e use entidades para refinar.
• Excesso de expressões regulares: padrões muito amplos criam falsos positivos; restrinja-os com limites de palavras e verificações de contexto.
• Solução genérica: Defina soluções alternativas em camadas: esclarecer → reformular → apresentar as principais intenções → escalar.
• Ignorando a realidade multilíngue: Adicione detecção precoce de idioma; direcione para o pipeline correto.
• Contexto ilimitado: Mantenha as janelas de sessão em um nível razoável; resuma as threads longas para evitar desvios do modelo.
  
  

‍

Juntando tudo

Um bot de PNL (Processamento de Linguagem Natural) de código aberto para WhatsApp não é um projeto de pesquisa — é um conjunto de partes práticas e combináveis ​​que você pode montar rapidamente e evoluir com segurança. Comece com um webhook verificado do WhatsApp, escolha um ambiente de execução que se adeque à sua equipe (Rasa para fluxos orientados por políticas, Botpress para orquestração visual, Haystack/LangChain para recuperação de dados) e crie conversas que perguntem apenas o necessário, um passo de cada vez. Meça os resultados, treine novamente semanalmente com base em transcrições reais e acione o suporte humano quando for realmente necessário.

Fazendo isso, você terá controle sobre seu planejamento, seus dados e seus custos, enquanto seus usuários desfrutam de uma experiência rápida, natural e útil no WhatsApp.

‍