Instale o widget

O widget do RolChat é um botão flutuante que se adapta aos módulos que você ativou: chat, formulário de pedido de retorno de ligação, agendamento de reuniões, formulário de leads e busca na base de conhecimento ficam todos dentro dele. Instale uma vez; o que ele mostra é decidido no painel.

1. Copie o snippet

Em Configurações → Widget, escolha o site e copie o snippet de instalação. Ele se parece com isto:

<!-- RolChat widget -->
<script>
  window.rolchatConfig = {
    "site_id": "ste_…",
    "account_id": "…",
    "widget_key": "wk1.<site>.<signature>",
    "modules": ["chat"]
  };
</script>
<script async src="https://widget.rolchat.com/stub.js"></script>

A chave do widget é pública e pode ser publicada em uma página com segurança. Ela identifica seu site e é assinada, então ninguém consegue apontar uma cópia do widget para a sua conta. O painel acrescenta outras chaves ao objeto (saudação, título do cabeçalho, tema, horário de atendimento, layout por viewport) conforme você altera as configurações do widget; copie o snippet de novo depois de alterá-las ou mantenha o objeto mínimo e deixe o widget buscar o resto.

stub.js tem poucos kilobytes e carrega o restante só quando o visitante precisa: a interface do chat na primeira abertura, o rastreamento após o consentimento, o banner de consentimento onde ele é obrigatório.

2. Cole-o antes de </body>

Adicione o snippet em todas as páginas onde você quer o widget, de preferência pelo template do site ou pelo gerenciador de tags, para que ele apareça em todo lugar de uma vez. O script carrega de forma assíncrona e não bloqueia a renderização; o pacote do primeiro carregamento é mantido pequeno de propósito para não afetar suas Core Web Vitals.

3. Confira se funciona

Abra seu site em uma janela privada. O botão aparece no canto que você escolheu. No painel, Visitantes mostra a nova sessão anônima em tempo real, e uma mensagem enviada pelo widget aparece na Caixa de entrada como uma nova conversa.

Identifique usuários logados

Se seus visitantes fazem login no seu produto, informe ao RolChat quem eles são para que as conversas sejam vinculadas ao contato certo:

window.rolchat.identify({
  email: "alice@example.com",
  first_name: "Alice",
  last_name: "Martin",
  phone: "+15551234567",
  external_id: "user_12345",
  custom_fields: { plan: "pro" },
});

Os atributos aceitos são email, phone, first_name, last_name, external_id e um objeto plano custom_fields; qualquer outra coisa é ignorada. O RolChat procura o e-mail no CRM. Se o contato existe, a sessão é vinculada a ele e o agente vê o perfil; se não existe, os dados são guardados e um lead é criado quando o visitante escreve pela primeira vez.

Para mais confiança, seu backend pode assinar a identidade: envie a assinatura que o RolChat emite para o usuário junto com os atributos, e a sessão só é promovida quando a assinatura é verificada. Chame window.rolchat.reset() quando o usuário sair; caso contrário, a próxima pessoa naquele navegador verá a conversa anterior.

A API JavaScript

window.rolchat fica disponível assim que o stub é executado; chamadas feitas antes de o pacote carregar entram em uma fila e são executadas em ordem.

Método	O que faz
show() / hide()	Mostra ou oculta o botão de abertura
open() / close()	Abre ou fecha o painel de chat
identify(traits)	Vincula a sessão a uma pessoa (acima)
reset()	Esquece a identidade e inicia uma nova sessão anônima
pushEvent(name, props)	Informa um evento personalizado para mensagens de gatilho e automação
trackPageView(path?)	Informa uma visualização de página em aplicações de página única
setLocale(code)	Troca o idioma do widget
showConsentPreferences()	Abre a central de preferências de consentimento
on(event, handler) / off(event, handler)	Inscreve-se em chat:opened, chat:closed, message:sent, message:received, session:started

window.rolchat.pushEvent("cart_abandoned", { value: 129.9, currency: "EUR" });
window.rolchat.on("message:received", () => audio.play());

Idioma e direção

O widget fala o idioma que você fixar com lang em window.rolchatConfig (por exemplo "lang": "de"); sem ele, o idioma do navegador do visitante, tomado na ordem das preferências do navegador entre os 40 idiomas que o RolChat suporta; se nenhum corresponder, o inglês. A configuração de idioma do próprio site não é usada: para que o widget fale o idioma do seu site, defina lang. Árabe e hebraico são exibidos da direita para a esquerda. As mensagens dos agentes não são traduzidas pelo widget; do lado do agente, é possível usar a tradução ao vivo por IA.

Cookies e consentimento

O widget não rastreia visitantes antes do consentimento onde um banner de consentimento é obrigatório. Se você usa o módulo Privacidade do RolChat, o banner e o widget compartilham um único estado de consentimento. Se você usa outra ferramenta de consentimento, os eventos de análise do widget aguardam o sinal que você configura em Configurações → Privacidade → Incorporar.

Onde o widget é configurado

O quê	Onde
Cores, posição, saudação, pontos de entrada, snippet de instalação	Configurações → Widget
Quais módulos aparecem dentro do widget	Configurações → Módulos (por site)
Horário de atendimento e mensagem offline	Configurações → Sites → Horário de atendimento
Mensagens de gatilho exibidas em páginas específicas	Marketing → Gatilhos