Controlar o chat pelo JavaScript do seu site

Atualizado em 07/10/2026

Colar o código do chat resolve a maioria dos casos: a bolha aparece no canto e pronto. Quando o seu site precisa de mais controle, existe uma API JavaScript. Ela fica disponível como window.Chat assim que o código carrega, e é por ela que você abre o chat no clique do seu botão, avisa quem acabou de fazer login e reage ao que acontece na conversa.

Site em React, Vue ou Angular

Essa é a dúvida mais comum de quem tem um site de página única, em que a navegação troca a tela sem recarregar o navegador.

A boa notícia: o código vai no HTML principal (o index.html) e é só isso. Como a troca de rota não recarrega a página, o chat continua montado e a conversa não se perde quando a pessoa navega. Você não precisa reinstalar nada a cada tela.

O cuidado real é outro, e é o que costuma passar despercebido: os dados do visitante são lidos uma vez, quando o código carrega. Num site de página única, a pessoa normalmente faz login depois disso. Se você só deixar os dados no HTML, o chat vai continuar achando que ela é anônima. A solução é avisar o chat quando o login acontecer:

Chat.identify({
name: usuario.nome,
email: usuario.email,
auth: usuario.auth, // opcional, da verificação de identidade
sig: usuario.sig,
})

O identify vale já na conversa aberta: o dado novo segue junto da próxima mensagem. Chame logo depois do login, e chame de novo sempre que algo mudar do seu lado — inclusive quando o token do usuário for renovado.

Na saída, o caminho é o oposto. Ao deslogar, use Chat.destroy() para remover o chat da tela e não deixar a identidade do usuário anterior para o próximo.

Abrir pelo seu próprio botão

Se você já tem um botão de ajuda no layout e não quer a bolha, esconda o lançador e conecte o seu elemento:

Chat.init({
key: 'a-chave-do-seu-chat',
hideLauncher: true,
launcherSelector: '#meu-botao-de-ajuda',
})

Ou chame Chat.open() no evento que você quiser, de qualquer lugar do seu código.

Mandar o texto da mensagem pelo seu sistema

Muitas vezes o seu sistema já sabe do que a conversa vai tratar: a pessoa está olhando um pedido, acabou de ver um erro, abriu um documento. Em vez de deixá-la descrever tudo de novo, o seu site entrega o texto pronto.

São duas chamadas, e a diferença entre elas é quem aperta o enviar:

// SUGERE: abre o chat com a mensagem escrita no campo — e não envia.
Chat.showNewMessage('Quero mudar a data de entrega do pedido 1234')

// MANDA: abre o chat e envia, como se a pessoa tivesse escrito.
Chat.startConversation('Deu erro ao emitir, pode verificar?')

Use a primeira quando você está sugerindo — a pessoa lê, completa com o que só ela sabe e manda. Use a segunda quando o seu sistema já sabe o que aconteceu e não há o que completar. As duas abrem o chat sozinhas: não é preciso chamar Chat.open() antes.

Havendo conversa em andamento neste navegador, a mensagem entra nela — o chat não recomeça do zero a cada chamada, e quem atende continua vendo o histórico. Quando cada chamada precisa mesmo começar uma conversa nova, use ephemeral: true no init.

Sem escrever código: pelo próprio código de instalação

Quando a mensagem é a mesma para a página toda, ela cabe na configuração — não é preciso chamar método nenhum:

Chat.init({
key: 'a-chave-do-seu-chat',
message: 'Deu erro ao emitir, pode verificar?',
send: true, // sem isto, a mensagem só fica escrita no campo
})

E no código pronto que você cola, pelos atributos:

<script src="https://…/chat.js"
data-key="a-chave-do-seu-chat"
data-message="Deu erro ao emitir, pode verificar?"
data-send="true"></script>

A mensagem entra quando o chat abre, uma vez por carga da página: fechar e reabrir não repete — senão a mesma frase sairia a cada clique. Sem send, o padrão é o mesmo do showNewMessage: escreve e espera a pessoa.

Enviar um arquivo junto

Na forma longa, a mensagem leva arquivos:

Chat.startConversation({
text: 'Analise este arquivo, está dando erro de duplicidade',
files: [arquivo],
})

Os arquivos são objetos File ou Blob do navegador. Podem vir de um campo de upload da sua tela, ou o seu próprio código pode buscá-los — é o seu sistema que tem a sessão da pessoa, então é ele que consegue baixar o que está protegido:

const blob = await fetch('/minha-api/documentos/123', { credentials: 'include' }).then((r) => r.blob())
const arquivo = new File([blob], 'documento-123.xml', { type: 'text/xml' })

Chat.startConversation({ text: 'Analise este documento', files: [arquivo] })

O agente lê o conteúdo do que você anexa — texto, XML, JSON, CSV, PDF, Word e planilha — e responde sobre ele; imagem ele enxerga. São até 5 arquivos por mensagem, de 10 MB cada. Se os anexos estiverem desligados na configuração do canal, a mensagem vai só com o texto.

Não passe uma URL em files. O endereço do arquivo costuma exigir a sessão de quem está navegando, e a plataforma não a tem; baixe no seu código, onde o acesso já existe, e entregue os bytes.

Chat dentro da página

Em vez de flutuar no canto, o chat pode morar dentro de um espaço fixo do seu layout, ocupando 100% do elemento que você indicar:

Chat.init({ key: 'a-chave-do-seu-chat', container: '#area-do-chat' })

Nesse formato costuma fazer sentido acertar o topo do chat para ele não competir com o cabeçalho da sua página. Dá para trocar o texto, tirar peças e até a pintura:

Chat.init({
key: 'a-chave-do-seu-chat',
container: '#area-do-chat',
title: 'Central de ajuda', // o nome exibido no topo
subtitle: 'respondemos rápido', // a linha de status ('' esconde)
showEndButton: false, // tira o "Encerrar" do topo
theme: { header: 'plain' }, // topo neutro, sem a cor da marca
})

O theme: { header: 'plain' } é o que costuma faltar quando o chat mora dentro de um painel do seu produto: sem ele, a faixa colorida da marca aparece no meio de uma interface que já tem identidade própria. A cor da marca continua valendo no resto do chat — balões, botões e destaques.

Esconder o WhatsApp numa página

Se você usa o mesmo chat em mais de um site ou produto, e o número de WhatsApp é de só um deles, esconda a opção nos outros com whatsapp: false. O ícone de continuar no WhatsApp some do topo e dos avisos do chat, mesmo com o WhatsApp ligado no canal:

Chat.init({
key: 'a-chave-do-seu-chat',
whatsapp: false,
})

No código pronto que você cola, o equivalente é data-whatsapp="false". Sem a opção, vale o que está configurado no canal.

O que você pode chamar

Os eventos que você pode escutar são open, close, start, message, end e expand. Dá para usar isso na sua própria medição, por exemplo marcando um evento de analytics quando uma conversa começa:

Chat.on('start', () => minhaAnalise.registrar('chat_iniciado'))

Chamar antes do código carregar

Se o seu script rodar antes do chat terminar de carregar, as chamadas não se perdem: elas ficam numa fila e são executadas assim que o bundle chega. Isso significa que você pode chamar Chat.identify(...) no seu fluxo de login sem se preocupar com a ordem de carregamento.

Opções úteis do init

• ephemeral: true: cada abertura começa uma conversa nova, sem retomar a anterior. Útil em quiosque ou terminal compartilhado, onde a próxima pessoa não pode ver a conversa da anterior.
• autoOpen: true: o chat já abre sozinho ao carregar a página.
• message e send: a mensagem que a página já sabe, escrita no campo quando o chat abre. Com send: true ela é enviada sozinha. Vale uma vez por carga da página.
• launcher: posição, cor, ícone, tamanho e distância da borda da bolha.
• meta: os dados que o seu site já sabe de quem está navegando (meta: { plano: 'pro' }). É por aqui que também vai o token do usuário logado, quando o agente consulta uma API sua que responde por usuário — o equivalente ao data-meta do código pronto. Veja Chat (widget do site).
• agentAvatar: a imagem ao lado das respostas automáticas, sem mexer no cadastro da marca. Ela também assume o topo quando o canal não tem imagem de logo própria. Hoje o caminho normal é a tela (Aparência › Avatar de quem responde), que vale sem recolar o código. Quando uma pessoa da equipe responde, aparece a foto dela; a ordem completa está em Referência: o que o chat envia e o que a sua API recebe.
• whatsapp: false: não oferece o WhatsApp nesta página, mesmo com ele ligado no canal (no código pronto, data-whatsapp="false").
• history: false: esconde a lista de conversas anteriores no menu (veja Conversas anteriores).
• colors e header: sobrepõem a aparência configurada na tela, só nesta página. colors aceita primary, message e action (com os pares onPrimary, onMessage e onAction); header aceita style, gradientTo, image, logo, showLogo, title, subtitle e showEndButton. A lista com os valores possíveis está na referência de integração.
• theme: forma antiga de pedir o topo neutro, { header: 'plain' }. Continua funcionando; em código novo, prefira header: { style: 'plain' }.

Token do usuário que expira

Se o agente consulta o seu sistema com o token de quem está na conversa, escrever esse token direto no código da página funciona só até ele vencer. A conversa continua por dias no mesmo navegador, então o valor colado no primeiro dia é o valor que sobra — e o sintoma aparece longe, com o agente dizendo que não conseguiu consultar.

Em vez do valor, entregue uma função. Ela é chamada quando o token é preciso: ao abrir a conversa, antes de cada envio e no instante em que o seu sistema recusa a credencial.

Chat.init({
key: 'a-chave-do-seu-chat',
credentials: {
// a chave é a mesma cadastrada na configuração da API
'X-Auth-Token': () => suaFuncaoQueDevolveOTokenAtual(),
},
})

A função pode ser assíncrona. Já com o chat montado, dá para registrar ou trocar uma credencial sem mexer no resto: Chat.setCredential('X-Auth-Token', () => token).

Recusada a credencial, a resposta é segurada em vez de sair errada: a plataforma pede o token novo à sua função, refaz a consulta e entrega a resposta de verdade. Quem perguntou não repete a pergunta nem recarrega a página. Sem a função declarada, a resposta sai explicando que o seu sistema recusou a credencial.

Esse token não fica junto do contexto livre: ele é guardado à parte, cifrado, e não aparece para quem atende no painel da conversa.

Limites e regras

• identify vale na conversa aberta. O dado novo segue junto da próxima mensagem, sem precisar fechar e abrir o painel. Numa aplicação de página única, chame no login e a cada renovação de token.
• Uma instância por página. Para mudar de formato (bolha, botão próprio, embutido), destrua antes de montar de novo.
• Chamadas antes do carregamento não se perdem — ficam numa fila e rodam quando o código chega.
• O que vai em meta fica gravado na conversa e é visto pelo atendente: no máximo 25 chaves, valor até 500 caracteres. O token do usuário é a exceção: ele é reconhecido pela chave cadastrada na API, guardado à parte e cifrado, e não aparece no painel de quem atende. Ainda assim, use um de vida curta e escopo mínimo.
• auth/sig nunca são gerados no navegador. O segredo mora no seu servidor; a página recebe só o resultado. Veja Verificação de identidade.

Dúvidas frequentes

O chat quebra o CSS do meu site? Não. Ele é renderizado dentro de um Shadow DOM, que isola os estilos nos dois sentidos: o seu CSS não vaza para dentro do chat, e o do chat não vaza para o seu site.

Posso ter o chat em mais de um lugar da mesma página? Não. É uma instância por página. Se precisar mudar o formato, use Chat.destroy() antes de um novo Chat.init().

O identify substitui a verificação de identidade? Não. Ele informa os dados; a verificação de identidade é o que prova que eles são verdadeiros. Para liberar dados privados, você precisa das duas coisas: os campos e a assinatura.