Skip to content

Chatbot

Lessa edited this page Oct 26, 2026 · 2 revisions

Chatbot

Como funciona o chatbot da BD no website: a página de conversa (/chatbot), a landing page de venda (/chatbot-lp), as rotas Next que fazem proxy para a API do chatbot e o controle de acesso. O modelo, as ferramentas e o histórico de conversas ficam na API do chatbot (CHATBOT_URL). O website não chama nenhum LLM.

Visão geral

Parte Arquivo Papel
Página de conversa pages/chatbot.js SSG. Envolve tudo em ChatbotAccessGate → ChatbotProvider → ChatbotContent
Landing page pages/chatbot-lp.js ISR (revalidate: 30). Hero, "por que usar", card de preço e FAQ
Lista de conversas context/ChatbotContext.js + hooks/useThreads.js Expõe threads, refetch e deleteThread para a sidebar
Mensagens e streaming hooks/useChatbot.js Cria thread, envia mensagem, lê o stream, feedback e exportação
Sessão no cliente hooks/useChatbotAuth.js Valida e renova o token antes de cada chamada
Auth no servidor lib/requireChatbotAuth.js Valida o token no backend e exige has_chatbot_access
Proxy pages/api/chatbot/* Repassa ao ${CHATBOT_URL}/api/v1/chatbot/... com Authorization: Bearer <token>

Para a organização geral de pages/api/, veja Rotas da API Next. Para pastas e convenções de componentes, veja Estrutura do front-end.

Fluxo de uma mensagem

navegador (useChatbot)              website (pages/api/chatbot/*)                API do chatbot (CHATBOT_URL)
────────────────────────────────────────────────────────────────────────────────────────────────────────────
sem thread? POST /api/chatbot/threads ──► requireChatbotAuth ──► POST /api/v1/chatbot/threads
            { title, language }                                  ◄── { id }
fetch POST /api/chatbot/messages?threadId=… ─► requireChatbotAuth ─► POST /api/v1/chatbot/threads/{id}/messages
            { content, stream: true }          axios (responseType: 'stream')
◄── NDJSON, uma linha por evento ◄──────────── repassa os chunks (res.write) ◄── stream
fim do stream: GET /api/chatbot/messages (silencioso) para trocar o estado local pelo histórico salvo
  • requireChatbotAuth chama a mutation verifyToken no backend (${NEXT_PUBLIC_API_URL}/api/v1/graphql). Sem token → 401; token inválido → 401; sem has_chatbot_access → 403.
  • O token vem do header Authorization ou do cookie token (getTokenFromRequest em lib/authCookie.js). O navegador nunca manda o token explicitamente: usa o cookie.
  • O título da thread são os primeiros 50 caracteres da primeira mensagem. language é o router.locale (pt/en/es), para a API responder no idioma do site.
  • Depois de criar a thread, a página grava o id na URL (/chatbot?t=<id>) com router.replace shallow.

Streaming

messages.js (POST) pede o upstream como stream e devolve Content-Type: application/x-ndjson com Cache-Control: no-cache, no-transform e X-Accel-Buffering: no, para nenhum proxy acumular a resposta. Ele respeita backpressure (pause/drain) e para de escrever se o cliente fechar a conexão. Erro >= 400 do upstream é lido inteiro e devolvido como JSON (ou texto).

No cliente, useChatbot lê o corpo com getReader(), quebra por \n e trata cada linha como JSON:

event.type O que o cliente faz
tool_call, tool_output Acrescenta em toolCalls da mensagem (aparece na seção "pensando")
final_answer Guarda data.structured_response e joga data.content no efeito de digitação
model_call_limit, error Joga data.content no efeito de digitação
complete Troca o id temporário pelo message_id real e tira o loading

O efeito de digitação (addToQueue/processQueue) roda a ~30 fps e acelera conforme a fila cresce. Respostas com mais de 40 linhas entram de uma vez.

Outros comportamentos de useChatbot:

  • Uma nova mensagem na mesma thread aborta o stream anterior (AbortController por thread).
  • A cada 60 s, se nada estiver gerando, recarrega as mensagens da thread aberta em silêncio.
  • 401/403 em qualquer chamada limpa a sessão (clearClientSession) e manda para /user/login.
  • follow_up_questions é normalizado para follow_up_prompts.

Rotas pages/api/chatbot/

Todas passam por requireChatbotAuth e repassam o status e o corpo de erro do upstream.

Rota Métodos Upstream (${CHATBOT_URL}/api/v1/chatbot/…) Uso
threads GET, POST, DELETE (?id=) threads, threads/{id} Listar, criar (201) e apagar conversas
messages GET, POST (?threadId=) threads/{id}/messages Histórico (sem cache) e envio com streaming
feedback PUT (?messageId=) messages/{id}/feedback Corpo { rating, comments }
exports POST (?messageId=&queryRef=&format=) messages/{id}/exports?query_ref=&format= Devolve uma url para baixar o resultado de uma query (padrão CSV)

Controle de acesso

O acesso ao chatbot é o campo has_chatbot_access do payload do token, definido pelo backend (assinatura ou trial do chatbot ativos). O website só lê esse campo.

  1. No cliente: ChatbotAccessGate não renderiza nada até liberar. Ele:
    • consome o UTM utm_campaign=chatbot_trial_followup (evento de GA e limpeza da URL) com consumeChatbotTrialFollowup;
    • sem cookie userBD válido → salva previousPath, limpa a sessão e vai para /user/login;
    • chama /api/user/validateToken. Falhou → login. has_chatbot_access: false → redirectToChatbotCheckout (utils.js), que grava o plano anual em plan_selected e leva a /user?plans_and_payment.
  2. No servidor: cada rota de pages/api/chatbot/ revalida com requireChatbotAuth. O gate do cliente é só UX; a proteção real é essa.

useChatbotAuth.ensureSession valida o token (com cache de 60 s no React Query, chave validateToken) e, se falhar, tenta /api/user/refreshToken antes de desistir.

Trial e assinatura

A assinatura e o trial do chatbot passam pelo Stripe (startChatbotTrial, planos bd_chatbot_month/bd_chatbot_year). Veja Stripe. Depois do pagamento, quem liga has_chatbot_access é o webhook do backend. Pagamento aprovado sem acesso costuma ser problema no backend, não no website.

Landing page (/chatbot-lp)

  • O Hero chama /api/user/validateToken. Com has_chatbot_access, o botão leva a /chatbot; sem, rola até o card de preço.
  • O card busca os planos em /api/stripe/getPlans (selectPlans) e consulta /api/user/getAlreadySubscribed?type=chatbot. Quem nunca assinou vê "Iniciar teste grátis"; quem já assinou vê "Assinar".
  • Ao clicar, grava plan_selected e manda para o login ou para plans_and_payment.

Componentes (components/organisms/chatbot/)

Componente O que faz
ChatbotAccessGate Gate de acesso descrito acima
Sidebar, ThreadList, UserMenu Lista de conversas (via useChatbotContext), apagar/recarregar, menu do usuário e "sair"
Search Campo de mensagem. Guarda rascunho no localStorage (chatbot_draft_<threadId|new>)
ChatWindow, Message Lista de mensagens, copiar, feedback (FeedbackModal)
ThinkingSection, toolViews Passos de ferramenta (tool_call/tool_output) em formato legível
StructuredResponse Fontes de dados (data_sources) e perguntas de continuação (follow_up_prompts)
Charts, VegaChart Gráficos de artefatos type: "chart" com vega-embed (carregado sob demanda)
DownloadResults Exportação de artefatos type: "export" (CSV, JSON, JSONL, AVRO, PARQUET) via /api/chatbot/exports
markdown, rehypeNumericTables Renderização do markdown da resposta, blocos de código e tabelas
OnboardingQuestions Sugestões de perguntas na tela de conversa nova (ui.onboarding.items)
AboutContent Tela "Sobre" dentro da página
user.js Lê e-mail/nome do cookie userBD para a saudação e o menu
BrandLogo, icons, PulseDotLoader, TextShimmer Visuais

Na conversa nova, a página mostra uma saudação aleatória por horário (ui.greetings), o campo de busca e as sugestões. A última saudação fica em localStorage (chatbot_last_greeting) para não repetir.

Conteúdo e traduções

Onde O quê
public/locales/{pt,en,es}/chatbot.json Textos da LP (head, hero, why, pricingCard, faq, banner), da interface (ui) e da tela Sobre (about)
content/chatbot/FAQ/{pt,en,es}/*.md FAQ da LP, lido no build por getAllFAQs(locale, "chatbot/FAQ")
public/chatbot/geo/*.topojson Malhas de estados e municípios para gráficos de mapa (licença em NOTICE.md). next.config.js serve com cache imutável de 1 ano

A LP também usa o namespace prices. Para adicionar texto, edite os três idiomas. Veja Internacionalização e domínios.

Variáveis de ambiente

Variável Uso
CHATBOT_URL Base da API do chatbot. Lida só no servidor (pages/api/chatbot/*)
NEXT_PUBLIC_API_URL Backend GraphQL, usado por requireChatbotAuth (verifyToken)
NEXT_PUBLIC_KEY_STRIPE Só para o checkout/trial. Veja Stripe

Em CI, CHATBOT_URL é secret do Environment, passado como build-arg nos releases de staging e produção. O release de dev não passa. Veja CI/CD e deploy.

Rodar e testar localmente

  1. Descomente CHATBOT_URL no .env (veja .env.example) apontando para uma API do chatbot acessível (local ou staging). Veja Setup local.
  2. NEXT_PUBLIC_API_URL precisa ser o mesmo backend que emite o token aceito pela API do chatbot.
  3. Faça login com uma conta que tenha has_chatbot_access (assinatura ou trial ativos nesse backend). Sem isso, /chatbot redireciona para o checkout.
  4. Abra /chatbot e envie uma mensagem. Na aba Network, a chamada messages?threadId=… deve ter tipo application/x-ndjson e receber linhas aos poucos.

Para conferir o acesso sem a interface, GET /api/user/validateToken devolve { success, has_chatbot_access }.

Problemas comuns

  • 503 Chatbot API URL is not configured: falta CHATBOT_URL. Só exports e feedback checam isso; threads e messages sem a variável chamam undefined/api/v1/... e respondem 500.
  • Redireciona sempre para o checkout: o token não tem has_chatbot_access. Confira a assinatura no backend, não no front.
  • Resposta aparece de uma vez, sem streaming: algum proxy na frente do Next está bufferizando. A rota já manda X-Accel-Buffering: no e no-transform.

Clone this wiki locally