Embutir um widget de chat sobre a base de conhecimento com lead capture

Transforme sua documentação em um assistente na porta

Sua base de conhecimento já contém as respostas que seus visitantes buscam. Um widget de chat embutido leva essas respostas ao seu site como porta de entrada conversacional: os visitantes fazem perguntas, o widget executa o mesmo pipeline RAG híbrido e a mesma infraestrutura de agente que seus times internos usam, e as respostas chegam com citações dos workspaces que você decidir expor. Este tutorial percorre o embed do widget, o controle sobre o que ele responde, a captura de leads e a correta configuração de CORS - do painel de administração a um snippet funcionando em poucos minutos.

O embed em duas etapas: um loader e um iframe em sandbox

O widget é construído em torno de um padrão de embed orientado à segurança. Em vez de injetar markup e estilos na sua página, o widget chega em duas etapas:

1. O script loader. Adicione uma única tag script ao site, apontada para o seu serviço de widget com o ID do widget. O loader é um pequeno arquivo JavaScript que cria um iframe na página hospedeira.
2. O painel iframe. O iframe carrega uma aplicação Preact autônoma - compilada como bundle IIFE com CSS inline - que desenha o botão flutuante, o painel de chat e cada interação dentro do seu próprio documento.

<script src="https://seu-simmetric-chat.com/widget/loader.js?widgetId=WIDGET_ID"></script>

Por que um iframe? Porque interpolar strings de conteúdo não confiável numa página hospedeira é o caminho clássico do XSS. Rodar a interface do widget dentro de um iframe em sandbox de origem opaca elimina por completo essa classe de risco: o conteúdo do chat nunca é executado no contexto da sua página. As antigas rotas de embed por interpolação de strings foram removidas do produto exatamente por isso, então o padrão em duas etapas não é uma opção entre várias - é o embed.

A comunicação entre iframe e página passa por um pequeno protocolo postMessage versionado (tipos de mensagem simmetric:*) que trata o abre/fecha do FAB, a recoloração do FAB e os handshakes do storage de sessão. Ambos os lados validam cada mensagem recebida contra o exato contentWindow esperado, de modo que mensagens forjadas entre iframes diferentes são ignoradas.

Criar o widget e apontá-lo para o conhecimento

Tudo começa no painel de administração:

1. Crie um widget em Configurações → Widgets. A criação é atrelada à licença (widget_enabled) e respeita o limite numérico de widgets do plano.
2. Vincule o widget a um ou mais workspaces. A whitelist de workspaces substitui atomicamente todos os vínculos anteriores, então estratificar o acesso à base de conhecimento é questão de quais workspaces anexar.
3. Configure o branding: cor primária, nome do bot, logos, posição (canto inferior direito ou esquerdo). As implantações de nível Community recebem valores padrão sensatos quando os campos estão vazios; a personalização completa e o white-labeling são flags enterprise.
4. Copie o snippet de embed para o HTML do seu site.

Como os widgets são definidos por workspace, o conhecimento de que um widget pode extrair é exatamente a união das bases de conhecimento dos workspaces vinculados - nada mais. Um widget de suporte pode ver o workspace de documentação pública sem nunca tocar os dados de projetos internos.

O model pin das respostas: resolvido no servidor

Uma adição recente conta para o controle de qualidade: a configuração de cada widget pode selecionar um provider e um modelo LLM específicos que servem as respostas de chat desse widget. O pin é conservado na linha do widget e resolvido no servidor a cada requisição de chat - nunca é fornecido pelo cliente, pelo proxy do widget ou pelo navegador do visitante. Um modelo fixado tem prioridade sobre o padrão do workspace, e os widgets sem pin mantêm a cadeia de resolução padrão. Na prática: seu widget de marketing pode rodar sobre o exato modelo que você verificou para respostas públicas, independentemente do que qualquer um manipule no lado do cliente.

Uma captura de leads que respeita os visitantes

A captura de leads do widget é projetada para a realidade de um formulário público: os abusos se concentram onde os dados são coletados, então o endpoint de leads é voluntariamente limitado a 3 requisições por hora por origem (com o limite visível ao usuário). O fluxo:

• O visitante vê uma barreira de consentimento sobre informações pessoais antes de conversar - um reconhecimento explícito de como os dados são tratados, não um link para uma política escondido no rodapé.
• Um cartão de lead coleta os dados de contato durante ou após a conversa, e os envios chegam à caixa de leads do widget no painel de administração, com exportação CSV para o seu pipeline.
• As sessões são anônimas por decisão de design: o servidor cria uma sessão com um token de 256 bits e validade de 24 horas, e cada requisição subsequente é validada contra ela. Os limites por sessão (20 mensagens por hora, 5 conversas por dia) devolvem um 429 com uma dica retryAfter quando excedidos, e a interface mostra um aviso de rate limit em vez de falhar em silêncio.

Os rate limits fazem parte da história de confiança, não são um acréscimo tardio: uma superfície de chat pública deveria degradar graciosamente sob carga ou abuso, e o limiter de leads é a barreira mais estreita dos três limiters do lado do widget.

CORS: fechado por padrão por design

O tráfego de widgets cruza origens por definição, então CORS faz parte da superfície de segurança em vez de ser um acréscimo tardio. Cada widget carrega sua própria lista allowedOrigins, editável no painel de administração. Em tempo de execução, um middleware CORS dinâmico valida o cabeçalho Origin de cada requisição contra a lista daquele widget - as requisições de origens não permitidas são rejeitadas no preflight, e o middleware falha em modo fechado: se a verificação de origem não puder consultar o banco de dados, o acesso é negado em vez de concedido.

Configure numa única passada:

• Adicione as origens do seu site (esquema e host, sem jogos com a barra final) às origens permitidas do widget.
• Lembre-se de que variantes de subdomínio contam como origens distintas - exemplo.com e www.exemplo.com são duas entradas.
• Use origens https:// em produção; o serviço de widget fala as mesmas regras de URL do resto da stack.

Todo o resto - a URL do loader, o iframe, o bootstrap da sessão, o stream SSE do chat - usa o mesmo host em que você implanta o serviço de widget, então há exatamente um lugar onde a confiança de origem é decidida: a lista permitida do widget.

O que roda onde

Um mapa de orientação rápido, porque o widget toca três processos:

• Servidor principal - CRUD e branding de widgets, vinculação de workspaces, a API interna que o serviço de widget chama com sua chave de API, e endpoints de lead/analytics para administradores. Todo o router interno devolve 402 quando a funcionalidade de widget está desligada.
• Serviço de widget - a superfície pública de embed: loader JS, HTML do iframe, criação de sessões, entrega da configuração em cache, o proxy SSE do chat para o servidor principal e o endpoint de leads. Ele se autentica no servidor principal com uma WIDGET_API_KEY e carrega seus próprios limitadores de frequência.
• O iframe - o cliente Preact IIFE com o ciclo de vida do chat: criação da sessão, streaming SSE token a token, exibição de citações, perguntas sugeridas e barreiras de consentimento.

O proxy do chat encaminha o mesmo formato de eventos da API de streaming interna - mensagens de status, anúncios de plano, tokens em streaming, citações e eventos terminais done/error - para que tudo o que sua equipe vê num chat de workspace, seus visitantes experimentem no widget.

Checklist de lançamento

• Widget criado, funcionalidade de licença ativa, workspaces vinculados
• Branding configurado; flag white-label se o widget não deve carregar a marca do produto
• Model pin das respostas definido na linha do widget (resolvido no servidor)
• Origens permitidas cobrindo cada site e subdomínio que o embutirá
• Lead capture verificado de ponta a ponta: barreira de consentimento, envio, caixa admin, exportação CSV
• Rate limits compreendidos: 3 leads por hora, 20 mensagens por hora por sessão, 5 conversas por dia

A partir daí, o widget é um drop-in: uma tag script, uma lista permitida, uma base de conhecimento em que você já confia. Quando seus visitantes fazem perguntas, eles obtêm respostas fundamentadas exatamente nos workspaces que você escolheu - com um pipeline de captura de leads que é cortês com humanos e severo com bots.

Leia o guia completo na documentação →