Repository navigation
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.
| 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.
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
-
requireChatbotAuthchama a mutationverifyTokenno backend (${NEXT_PUBLIC_API_URL}/api/v1/graphql). Sem token →401; token inválido →401; semhas_chatbot_access→403. - O token vem do header
Authorizationou do cookietoken(getTokenFromRequestemlib/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é orouter.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>) comrouter.replaceshallow.
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 (
AbortControllerpor thread). - A cada 60 s, se nada estiver gerando, recarrega as mensagens da thread aberta em silêncio.
-
401/403em qualquer chamada limpa a sessão (clearClientSession) e manda para/user/login. -
follow_up_questionsé normalizado parafollow_up_prompts.
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) |
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.
-
No cliente:
ChatbotAccessGatenão renderiza nada até liberar. Ele:- consome o UTM
utm_campaign=chatbot_trial_followup(evento de GA e limpeza da URL) comconsumeChatbotTrialFollowup; - sem cookie
userBDválido → salvapreviousPath, 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 emplan_selectede leva a/user?plans_and_payment.
- consome o UTM
-
No servidor: cada rota de
pages/api/chatbot/revalida comrequireChatbotAuth. 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.
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.
- O Hero chama
/api/user/validateToken. Comhas_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_selectede manda para o login ou paraplans_and_payment.
| 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.
Nota: o onboarding do chatbot está sendo reformulado (branch
feat/onboarding-v2), incluindo a tela de conversa nova e nomes de arquivos desta pasta. Confira a branch antes de mexer nessa parte.
| 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á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.
- Descomente
CHATBOT_URLno.env(veja.env.example) apontando para uma API do chatbot acessível (local ou staging). Veja Setup local. -
NEXT_PUBLIC_API_URLprecisa ser o mesmo backend que emite o token aceito pela API do chatbot. - Faça login com uma conta que tenha
has_chatbot_access(assinatura ou trial ativos nesse backend). Sem isso,/chatbotredireciona para o checkout. - Abra
/chatbote envie uma mensagem. Na aba Network, a chamadamessages?threadId=…deve ter tipoapplication/x-ndjsone receber linhas aos poucos.
Para conferir o acesso sem a interface, GET /api/user/validateToken devolve { success, has_chatbot_access }.
-
503 Chatbot API URL is not configured: faltaCHATBOT_URL. Sóexportsefeedbackchecam isso;threadsemessagessem a variável chamamundefined/api/v1/...e respondem500. -
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: noeno-transform.