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" (entenda a linguagem, os erros de digitação e a intenção) não significa ficar preso a uma caixa-preta proprietária. Com stacks maduros de processamento de linguagem natural (PLN) de código aberto, você pode criar um bot para WhatsApp sobre o qual tenha controle total — incluindo dados, lógica e custos — e, ao mesmo tempo, oferecer uma experiência aprimorada e 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 o WhatsApp NLP?

• Controle sobre dados e privacidade. Mantenha dados de treinamento, logs 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 reescrever tudo.
• Transparência de custos: pague por hospedagem/computação, não por marcações por mensagem de complementos “inteligentes”.
• Velocidade da comunidade: Rasa, Haystack, spaCy e LangChain evoluem rapidamente e fornecem padrões comprovados que você pode adaptar.
  
  

‍

Bot NLP do WhatsApp: a arquitetura mínima (e onde o código aberto se encaixa)

1. Transporte (Plataforma WhatsApp Business):
   
   • Use a plataforma WhatsApp Business da Meta (API em nuvem) como canal oficial. Ela envia mensagens para o seu webhook e permite que você envie respostas.
   • Você hospedará um pequeno receptor de webhook (FastAPI/Express) para verificar assinaturas, analisar JSON de entrada e encaminhar um evento normalizado para o tempo de execução do seu bot.
     
     
2. Tempo de execução do bot (código aberto):
   
   • NLU e Gestão de Diálogo:
     
     • Rasa (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 se você planeja usar modelos generativos)
       
       
   • Recuperação e Conhecimento:
     
     • Haystack ou LangChain + um vetor DB (FAISS ou Chroma) para RAG (geração aumentada de 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 você estiver criando um protótipo).
     
     
4. Administração e ferramentas:
   
   • Anotação e controle de versão 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 meta).
     
     

A transferência é simples: WhatsApp → webhook → tempo 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 em batalha para extração de intenção/entidade, formulários (preenchimento de slots), histórias, políticas; bom equilíbrio entre baseado em regras e ML.
• Botpress (edição de código aberto) – criador de fluxo visual; rápido para integrar não desenvolvedores; use quando sua equipe quiser um canvas mais NLU.
• 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, armazenamentos de documentos, recuperadores, leitores; ideal para bots de FAQ + base de conhecimento.
• LangChain/LangGraph – agentes/ferramentas componíveis para designs centrados em LLM; emparelhe com um modelo aberto ou um modelo de API, conforme necessário.
• FAISS / Chroma – busca de vetores leves para recuperação baseada em embeddings.
• Node-RED – cola de baixo código para orquestrar webhooks, chamadas HTTP e tomada de decisões quando você deseja enviar rapidamente.
  
  

‍

Modelo de dados e normalização de mensagens

Os payloads do WhatsApp variam de acordo com o tipo de mensagem. Normalize com antecedência para que sua pilha de PNL veja um esquema consistente:

• carimbo de data/hora (ISO)
• de_telefone (E.164)
• message_type (texto | imagem | localização | áudio | documento)
• texto (texto extraído; execute OCR para imagens somente se você realmente precisar)
• media_url (se aplicável)
• localidade (se presente; fallback com 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 esclarecedoras e armazene referências para revisão humana.

‍

Três padrões de exemplo de código aberto (prontos para cópia)

1) FAQ + qualificação de leads (Rasa-first)

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

Fluxo:

1. Texto de entrada → Rasa NLU → intenção (consulta_de_preço, instalação_de_livro, fora_do_escopo).
2. Se pricing_query, extrai entidades (cidade, tipo_de_sistema); se ausente, os formulários fazem perguntas.
3. Recupere respostas prontas de um arquivo de conhecimento YAML/JSON ou de um RAG simples se o conteúdo for grande.
4. Entregue ao humano se a confiança for < limite ou o formulário expirar.
   
   

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

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

Quando escolher: A base de conhecimento é grande (PDFs, documentos, perguntas frequentes) e você quer respostas baseadas no seu conteúdo.

Fluxo:

1. Texto de entrada → detecção de idioma → consulta incorporada.
2. Haystack : O Retriever (por exemplo, Dense Passage Retrieval) busca as principais passagens do FAISS/Chroma.
3. O leitor/gerador compõe uma resposta curta com citações.
4. A resposta inclui um rótulo de fonte amigável (“Guia de Instalação §2.1”).
   
   

O melhor: você evita alucinações com um aterramento rigoroso. Você pode expandir o conteúdo sem afetar a lógica do diálogo.

3) Triagem de serviço orientada por fluxo (regras Botpress + spaCy)

Quando escolher: As operações dependem de fluxos de trabalho estruturados (abertura de ticket, atualização de ETA, reagendamento) e você deseja uma tela visual compartilhada.

Fluxo:

1. Fluxo de Botpress para ramificações de alta confiança (menu, etapas de formulário).
2. O componente personalizado spaCy marca números de pedidos, e-mails e datas.
3. O Botpress chama um backend (por exemplo, /tickets/create) e publica 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: pessoas que não são desenvolvedores podem ajustar os fluxos com segurança. As regras do spaCy capturam 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 cobrindo 80% do tráfego. ~20 a 30 exemplos por intenção é um MVP saudável.
• Entidades: Concentre-se nas entidades operacionais (cidade, ID do pedido, nível do produto). Escreva alguns recursos de expressão regular (IDs do pedido, e-mails) para aumentar a precisão.
• Exemplos negativos: inclua conversas fora do escopo e conversas informais educadas para que a política de contingência tenha força.
• Multilíngue: se você espera idiomas mistos, adicione detecção de idioma e direcione para pipelines ou modelos separados por idioma.
  
  

Conjuntos de dados de versão com Git + DVC. Cada construção de modelo deve ser vinculada a um commit de conjunto de dados.

‍

Design de conversação escalável

• As duas ou três principais sugestões depois de uma resposta alternativa (“Você quis dizer preço ou tempo de instalação?”) superaram “desculpe, não entendi”.
• Divulgação progressiva: peça um espaço faltante por vez, resuma as informações coletadas e confirme antes de agir.
• Human-in-the-loop: forneça uma palavra-chave como “agente” ou simplesmente detecte padrões de frustração e intensifique com o contexto da transcrição.
  
  

‍

Segurança, conformidade e especificações do WhatsApp

• Opt-in + opt-out: imponha um consentimento claro. Faça com que o "STOP" (ou variante local) funcione desde o primeiro dia.
• Minimização de PII: armazene apenas os campos realmente necessários (por exemplo, order_id, city). Mascare ou faça hash de identificadores sensíveis em logs.
• Limites de taxa e novas tentativas: implemente recuo exponencial para erros de envio; registre códigos de resposta.
• Modelos de mensagens: para mensagens iniciadas por empresas fora do período de 24 horas, prepare modelos aprovados (requisito do WhatsApp).
• Higiene da mídia: não baixe anexos automaticamente às cegas; faça uma varredura se a conformidade exigir.
  
  

‍

Observabilidade: medir o que importa

• Matriz de precisão e confusão de intenção: encontre intenções semelhantes e mescle ou reformule exemplos.
• Taxa de conclusão de metas: porcentagem de usuários que alcançam um resultado comercial (reserva, criação de tíquetes).
• Taxa de fallback por tipo de mensagem: acompanhe se há picos de fallback para determinados idiomas ou campanhas.
• Taxa de transferência humana e motivos: use categorias (cobrança, caso extremo, abusivo) para priorizar o treinamento.
• Latência (p50/p90): Mantenha as respostas de texto de ponta a ponta abaixo de 2–3 segundos.
  
  

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

‍

Manual de início rápido (caminho de uma semana)

Dia 1 – Esqueleto

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

Dia 2 – Intenções e formas

• Defina 10 intenções e 3 entidades; adicione 20 amostras/intenção.
• Crie um formulário (por exemplo, reserva: data, cidade, e-mail de contato).
• Adicione um limite de política; direcione a baixa confiança para o fallback.
  
  

Dia 3 – Conhecimento

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

Dia 4 – Transferência humana

• Implemente um comando de escalonamento e uma caixa de entrada para agentes (até mesmo uma ponte compartilhada de e-mail/slack no início).
• Transcrições de log com tags (“precisa de escalonamento”).
  
  

Dia 5 – Ciclo de avaliação

• Crie um pequeno grupo e colete mensagens classificadas incorretamente.
• Retreinar; comparar F1 e matriz de confusão.
  
  

Dia 6 – Modelos e horas extras

• Adicione modelos de mensagens do WhatsApp para fluxos iniciados por empresas.
• Respostas baseadas em tempo (“Voltaremos às 09:00”) com uma tarefa de acompanhamento matinal.
  
  

Dia 7 – Endurecimento

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

‍

Dicas de custo e desempenho

• Modelos: Comece com backbones de transformadores leves (classe DistilBERT) ou até mesmo SVM/fastText clássico para intenções se o orçamento estiver apertado.
• Pesquisa de vetores: FAISS na CPU geralmente é suficiente para <500 mil passagens.
• Cache: armazene em cache respostas frequentes (por exemplo, tempos de entrega) para reduzir a computação.
• 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)

• Inchaço de intenção: mais de 30 intenções granulares muito cedo aumentam a confusão. Consolide e use entidades para refinar.
• Excesso de expressão regular: padrões muito amplos criam falsos positivos; restrinja com limites de palavras e verificações de contexto.
• Alternativa única para todos: defina alternativas em camadas: esclareça → reformule → ofereça as melhores intenções → escale.
• Ignorando a realidade multilíngue: adicione detecção precoce de idioma e direcione para o pipeline certo.
• Contexto ilimitado: mantenha as janelas de sessão razoáveis; resuma threads longos para evitar desvios do modelo.
  
  

‍

Juntando tudo

Um bot de PNL 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 desenvolver com segurança. Comece com um webhook do WhatsApp verificado, escolha um tempo de execução adequado à sua equipe (Rasa para fluxos baseados em políticas, Botpress para orquestração visual, Haystack/LangChain para recuperação) e crie conversas que perguntem apenas o que é necessário, passo a passo. Mensure os resultados, treine semanalmente com transcrições reais e encaminhe para humanos quando realmente for útil.

Faça isso e você será o dono do seu roteiro, dos seus dados e dos seus custos, enquanto seus usuários aproveitam uma experiência rápida, natural e útil no WhatsApp.

‍