Chatbot embutível: segurança, slug e domínio restrito

O que é o chatbot embutível?

É um assistente de IA que você instala no seu site colando uma única tag script. Ele aparece como uma bolha no canto da página, abre um painel de conversa e responde com base na configuração feita no módulo Chatbot da PowerVizion: persona, base de conhecimento, temas permitidos, saudação, sugestões de perguntas e mensagem de fallback.

O snippet tem o formato de uma tag script que aponta para o loader da PowerVizion e carrega dois atributos: data-slug, que identifica a configuração, e data-position, que define o canto da tela. O atributo data-slug é obrigatório. Sem ele, o loader registra o erro no console e não faz nada.

Como o widget funciona por dentro

O loader cria um contêiner fixo e, dentro dele, um iframe que aponta para uma página de chat servida pela própria API. Quando o visitante abre o painel, o iframe avisa o loader por postMessage, e o contêiner passa de bolha para painel. Em telas estreitas, de até 480 pixels, o painel ocupa a janela inteira.

Esses arquivos são servidos pelo próprio servidor, sem passar pelo build do front-end. Por isso, uma correção no widget chega a todos os sites sem que o cliente precise atualizar nada.

A aparência também é configurável por tokens de fonte, cor, raio e espaçamento. Uma falha ao carregar o tema salvo nunca derruba o widget: ele cai no tema padrão. Uma falha ao ler a lista de domínios, por sua vez, cai no lado mais restrito, em que o widget só é aceito dentro do próprio domínio da PowerVizion.

Slug e domínios permitidos

O slug é um identificador único da configuração, e é público: qualquer pessoa que veja o código do seu site o enxerga. A proteção, portanto, não está em esconder o slug. Está na lista de domínios autorizados, que o administrador informa um por linha, com suporte a curinga de subdomínios (por exemplo, *.exemplo.com).

O servidor aplica a lista em duas camadas. Primeiro, confere o cabeçalho Origin de cada requisição ao bootstrap e ao envio de mensagem, usando o Referer só quando o Origin não existe, e ignora cabeçalhos customizados que um cliente poderia forjar. Depois, a página do chat é entregue com uma política de frame-ancestors derivada da lista, de modo que o navegador se recusa a exibir o widget dentro de sites não autorizados.

Na prática, o fluxo de instalação é curto: crie a configuração, preencha os domínios do seu site, copie o snippet e publique. Vale testar em um ambiente de homologação antes, incluindo o comportamento de um domínio não listado, que deve receber a resposta de acesso negado.

Outros controles: limite, sessão e escopo

A conversa tem controles adicionais de abuso e de conteúdo.

Cada resposta gera um evento de uso no workspace, com os tokens reais reportados pelo provedor, o que permite acompanhar o custo do chatbot no painel Uso & Custos junto com o dos demais agentes.

• Limite de uso: 20 mensagens por minuto por combinação de slug e IP.
• Tamanho: mensagens acima de 1.200 caracteres são rejeitadas.
• Sessão: o identificador é gerado pelo servidor, e valores enviados pelo cliente só são aceitos se tiverem o formato esperado, o que impede ler sessões alheias.
• Contexto: o histórico considera as últimas 8 mensagens da sessão.
• Escopo: o assistente só responde dentro dos temas configurados e usa a mensagem de fallback fora deles. Ele é instruído a não inventar funcionalidades e a responder em poucas frases.
• Feedback: as avaliações de polegar são validadas contra o slug antes de serem gravadas.

Como a PowerVizion aborda dados sensíveis no embed

Para variantes do widget conectadas a dados de clientes finais, a regra é mais rígida. A lista de domínios vazia nega o acesso, em vez de liberar. O assistente só pode usar um pequeno conjunto de ferramentas de leitura, e toda ferramenta nova nasce desligada até ser incluída de propósito.

Consultas que exporiam dados pessoais a partir de um documento informado por um visitante anônimo foram retiradas do widget público. A decisão é tratar o visitante como não identificado até existir verificação de titularidade, como um código por mensagem. Ações com efeito, como abrir um pedido, continuam fora do embed.

Limites atuais

A lista de domínios é uma barreira de navegador, não uma autenticação. Uma ferramenta fora do navegador pode enviar o cabeçalho Origin que quiser, e por isso o limite de mensagens e a ausência de ferramentas sensíveis seguem importantes. Se a lista estiver vazia no widget genérico, qualquer site que conheça o slug consegue embutir o assistente, e a interface avisa isso ao administrador.

O limite de mensagens é mantido na memória de cada processo do servidor, então reinicia junto com ele. As conversas são gravadas para consulta pelo workspace, o que pede um aviso claro aos visitantes na política de privacidade do seu site. E, como em todo assistente baseado em modelo de linguagem, as respostas podem errar, e a qualidade depende da base de conhecimento que você configurou.

Perguntas frequentes

Como coloco o assistente da PowerVizion no meu site?

Crie uma configuração no módulo Chatbot, copie o snippet com a tag script e o atributo data-slug e cole-o no HTML do site. A configuração define persona, base de conhecimento e temas.

O que a lista de domínios permitidos faz?

Restringe em quais sites o widget funciona: o servidor valida a origem das requisições e o navegador recusa exibir o widget em sites não listados. Ela aceita curinga de subdomínio.

O slug precisa ser secreto?

Não. Ele é visível no código da página. A proteção vem da lista de domínios, do limite de mensagens e do escopo configurado.

O assistente responde fora da base de conhecimento?

Não deve. Ele é orientado a responder só dentro dos temas configurados e a usar a mensagem de fallback quando a pergunta foge do escopo.