Chat no seu site: da instalação ao primeiro atendimento

Atualizado em 19/10/2026

O chat do site coloca uma bolha de conversa nas suas páginas. O visitante clica e fala com você na hora, e a conversa entra em Atendimento › Conversas como qualquer outra conversa: com histórico, responsável, transferência e relatórios. Quem responde pode ser um agente de IA, um fluxo de triagem ou a sua equipe. Este guia percorre tudo: instalar, escolher quem atende e testar antes de publicar.

Instale com um código

Abra Administração › Configurações › Canais › Chat. Cada marca cadastrada já vem com o seu chat pronto, com código, boas-vindas e quem atende. Escolha o jeito de aparecer no site:

• Bolha no canto: o jeito clássico. Nada além de colar o código.
• No seu botão: um botão que já existe no site abre o chat.
• Dentro da página: o chat mora num espaço fixo do seu layout.
• Tela de conversas: tela inteira, no formato dos assistentes de IA. Barra lateral com as conversas da pessoa (busca e "Nova conversa"), tela inicial com as sugestões e a conversa no centro. É a opção para quem quer um item "Conversas" no menu do próprio sistema; com identidade assinada, a lista acompanha a pessoa em qualquer navegador.

Copie o código exibido e cole antes do </body> nas páginas da marca. Pronto, o chat entra no ar. É um endereço só — o do arquivo do chat, mais a chave da sua marca: não há servidor nem endereço de API para preencher à mão.

Um detalhe que economiza tempo: o quadro ao lado da configuração é o widget de verdade. O que você digitar ali vira uma conversa real, perfeito para testar antes de colar o código no site.

Vai pedir para uma IA instalar?

Se quem vai mexer no site é uma IA de programação (um assistente de código), não descreva a tarefa com as suas palavras: use o guia pronto, na faixa logo abaixo do código de instalação. Ele sai preenchido com a sua chave, os seus endereços e os nomes exatos que a sua conta usa — o que está preenchido a IA não inventa. Dá para copiar o guia inteiro e colar na conversa, ou copiar só o link e mandar a IA ler. O guia termina com um teste que a própria IA roda para provar que a integração ficou certa antes de publicar.

Quem atende: três jeitos de receber

No card Quem atende, você escolhe quem responde as novas conversas deste chat. São três modos, e dá para trocar quando quiser:

1. Agente de IA (automático, 24h): responde na hora usando o conhecimento que você cadastrar e transfere para a equipe quando precisa. Ideal quando você quer resposta imediata, mesmo sem ninguém online.
2. Fluxo de entrada (você desenha): faz a triagem e encaminha cada conversa para o destino certo, por menu ou pelo que já sabe de quem chamou. Cada caminho pode levar a um agente de IA ou a uma fila. Ideal quando você tem mais de um assunto ou equipe.
3. Só minha equipe (toque humano): toda mensagem cai direto para os atendentes, sem nada no meio. Ideal quando você prefere cuidar de cada conversa pessoalmente.

Os modos se combinam: dentro de um fluxo de entrada, um caminho pode ir para o agente de IA e outro direto para a equipe. Na dúvida, o link Qual escolher? na própria tela compara os três.

A escolha salva sozinha ao clicar. Se você tem um agente só, ele conecta direto; com mais de um, a tela pede para escolher qual.

Quando só a equipe atende

• Boas-vindas: a primeira mensagem que o visitante vê ao abrir o chat. Se deixar em branco, vale "Olá! Como podemos ajudar?". Com agente de IA conectado, a abertura passa a ser a saudação do agente.
• Fila certa: a conversa entra sem equipe e vai para o próximo atendente do Roteamento de chamados; quem coloca numa equipe é o fluxo, o agente de IA ou o próprio atendente, ao transferir. Nas equipes (Administração › Configurações › Atendimento › Atendentes › Equipes) você define o roteamento: rodízio (cada conversa vai para um atendente disponível, um de cada vez) ou fila compartilhada (todos veem; quem pegar primeiro, atende).
• Horários: em Administração › Configurações › Atendimento › Atendentes › Horários você decide se o chat fica sempre aberto ou só na janela de atendimento. Fora do horário, o widget se mostra offline e o visitante deixa mensagem, que vira chamado. Com agente de IA ou fluxo, o chat conversa 24h.
• Atender: a equipe trabalha em Atendimento › Conversas. O botão Atender próximo puxa a conversa mais antiga da fila, respeitando suas filas e seu limite de conversas simultâneas.

Teste antes de publicar

• Prévia real: o widget ao lado da configuração é o chat de verdade, com a cor e a logo da marca.
• Testando como: se o seu agente ou fluxo usa dados do visitante, este card simula um visitante de teste: nome, e-mail e outros campos. Dá até para testar como verificado, simulando um visitante com identidade confirmada pelo site. Os valores ficam só no seu navegador, nada é salvo.
• Abrir em tela cheia: abre uma página de demonstração em nova aba, simulando o site do cliente com a bolha no canto, já com os dados de teste que você digitou.

Passar o token de quem está logado no seu site

Quando o agente consulta uma API sua que responde por usuário (o que a pessoa contratou, o andamento do que ela pediu, os dados da conta dela), essa API precisa saber de quem se trata. No card Teste como você digita esse token à mão para experimentar; no site ele viaja junto com o código de instalação, na linha data-meta, só nas páginas com login. O código que a tela mostra em cima é sempre o padrão, sem token: é o que vai no site público, onde ninguém está logado e quem conversa entra como visitante. A versão com token fica em Quem está logado no seu site, logo abaixo do código:

<script src="https://SEU-APP/widget/chat.js"
data-key="a-chave-do-seu-chat"
data-meta='{"X-Auth-Token":"TOKEN_DO_USUARIO_LOGADO"}'></script>

O nome da chave (X-Auth-Token é só um exemplo) é o que você definiu ao cadastrar a API — ele varia de sistema para sistema, e a plataforma não escolhe por você. Quando existe uma API assim, o passo Pegue o token da sessão aparece em Quem está logado no seu site, e o código desse modal já vem com o nome certo. Se o login acontece sem recarregar a página, escolha Depois do login, sem recarregar: o código passa a ser uma chamada a Chat.setCredential no fim do login.

Três cuidados, e são os que separam uma integração segura de um vazamento:

• Um token por usuário, gerado no seu servidor a cada carregamento da página. Ele fica visível para quem abrir o código-fonte no navegador, então nunca use uma chave mestra nem uma credencial de administrador.
• Curto e revogável. Se o token expira junto com a sessão do seu site, um valor copiado da tela deixa de servir logo. E token com prazo pede a forma abaixo: colado no código da página, ele vence no meio da conversa.
• Junto com a assinatura de identidade. Sem data-auth/data-sig, a sua API recebe verified: false — e nesse caso não deve devolver dado privado. Veja Verificação de identidade.

Token que expira? Mande uma função. A conversa é retomada por dias no mesmo navegador, então o valor colado no primeiro dia é o que sobra. Declarando credentials: { 'X-Auth-Token': () => token } no Chat.init, a plataforma pede o valor ao seu site quando precisa — inclusive no instante em que a sua API recusa o token, quando a resposta é segurada, o token novo é pedido e a consulta refeita. Os detalhes estão em Controlar o chat pelo JavaScript do seu site.

A mesma linha serve para o que não é credencial: qualquer chave que você mandar ({"plano":"pro"}) fica disponível para o agente e para os fluxos decidirem o caminho. Sem isso, a resposta sai genérica.

A cara do chat: cores, topo e logo

Em Administração › Configurações › Canais › Chat, etapa Aparência você acerta o visual sem tocar no código — e o que muda ali passa a valer nas páginas onde o código já está colado, sem recolar nada.

• Três cores: o topo, a bolha do visitante e os botões. A cor da letra não é campo: ela sai por contraste, para o texto nunca sumir sobre uma cor clara.
• Fundo do topo: cor sólida, degradê, imagem ou neutro (sem cor nenhuma).
• Logo do topo e avatar de quem responde: podem ser imagens diferentes — a marca por extenso em cima, um ícone quadrado ao lado das respostas.
• Título e linha de apoio do topo, para dizer o que aquilo faz ("Pergunte o que quiser") em vez de repetir o nome da marca.

A prévia ao lado mostra o resultado enquanto você mexe. Quando uma página precisa fugir do padrão (a área logada com outra cor, por exemplo), o código também aceita cores e topo próprios — está na referência de integração.

Se o agente conectado só atende cliente identificado (recurso Subcontas), há mais um passo, e ele é o que costuma confundir: marcar "verificado" não basta. Verificado prova quem é a pessoa; o que o agente exige é saber de qual cliente ela é. Abra Subcontas, dentro do próprio "Teste como", e escolha o cliente — a tela busca pelo nome ou pela referência e já diz se ela casa com alguém. Sem isso, o teste reproduz o bloqueio real: o agente não responde e a conversa vai para a fila da equipe, com o aviso explicando o motivo dentro da própria prévia.

Recursos extras

• Anexos: o visitante manda arquivo ou imagem direto na conversa (um print resolve em segundos o que três mensagens não explicam). Vem ligado; o que ele envia fica na conversa. Desligue no cartão de recursos do chat.
• Mensagem de voz: o visitante grava e envia um áudio, como faria no WhatsApp. Vem desligado — ligue no mesmo cartão. Com agente de IA ou fluxo atendendo, o áudio vira texto para o atendimento entender e responder, e essa transcrição conta como consumo de IA. Só com equipe humana, o atendente ouve o áudio na conversa.
• Tabelas e gráficos: quando a resposta tem dados, o agente monta a tabela (e o gráfico, quando ajuda) dentro da conversa. Um botão na mensagem baixa em Excel ou PDF — o arquivo é montado no próprio navegador, nada fica guardado em servidor.
• Apresentação de quem atende: enquanto a IA responde, o visitante vê a identidade da marca. Quando alguém da equipe assume, as respostas passam a sair com o primeiro nome e a foto de quem está falando, e é assim que a pessoa percebe que agora tem gente do outro lado. Vem ligado, no cartão "A conversa" do chat. Quem não quiser aparecer desliga só para si em Meu perfil, e quem não tem foto aparece com a inicial e o primeiro nome.
• Conversas anteriores: no menu do chat, o visitante relê o que já falou com você e retoma de onde parou. Regras de privacidade e como desligar em Conversas anteriores.
• Continuar no WhatsApp: um ícone no topo do widget deixa o visitante levar a conversa para o app sem perder o histórico. QR no computador, um toque no celular. Usa o mesmo chat em mais de um site e o número é de só um deles? Dá para esconder o ícone por página — veja Controlar o chat pelo JavaScript.
• Dizer ao chat quem está navegando: se o seu site já sabe quem é a pessoa, envie junto no código (data-name, data-email, data-meta). O atendente vê tudo antes de responder, e esses dados viram variáveis para o agente de IA e para os fluxos decidirem o caminho.
• O seu site já manda a mensagem: quando a página já sabe do que se trata (deu erro numa emissão, a pessoa está olhando um pedido), o código pode entregar a mensagem pronta — escrita no campo para a pessoa conferir, ou enviada sozinha com data-send="true". Um botão seu também pode abrir o chat já com o texto, e até com um arquivo anexado para o agente analisar. Como fazer em Controlar o chat pelo JavaScript.
• Verificação de identidade: para a sua integração confiar no e-mail do visitante, o site pode assinar a identidade com uma chave secreta. Com a assinatura exigida, identidade sem assinatura não vira cadastro; a conversa acontece igual, só fica anônima.
• Mais de um chat: site, área logada, portal de parceiros. Cada um com o seu código, a sua equipe e o seu quem atende.
• Clientes de parceiros (revenda): se você atende clientes que usam o seu produto com a marca de um parceiro, o chat pode esconder deles o link Abrir na Central de Ajuda do fim dos artigos. Na seção Tela inicial do chat, com o link ligado, abra Atende clientes de parceiros (revenda)? e informe o atributo que o seu site manda no data-meta (por exemplo marca) e os valores da sua marca, separados por vírgula. Quem chega com outro valor continua lendo o artigo dentro do chat, sem ir para a sua Central. Quem chega sem o atributo vê o link normalmente.

Limites e regras

• Um chat por marca, cada um com a sua chave e o seu segredo. O consumo de todos cai na sua conta.
• Dados enviados pelo código são declarados, não provados. Só a assinatura (data-auth/data-sig) transforma isso em identidade confiável — é o que decide se a resposta pode incluir dado privado.
• O contexto livre fica gravado na conversa e o atendente o vê: até 25 chaves, valor até 500 caracteres.
• Trocar o segredo derruba as assinaturas antigas na hora, sem período de convivência.
• Anexos e voz valem daqui para frente: desligar um deles não apaga o que já está na conversa.
• A lista completa de atributos, campos e o que a sua API recebe está em Referência: o que o chat envia e o que a sua API recebe.

Dúvidas comuns

• Como sei se o visitante leu minha resposta? Pelos tiques ao lado da hora da resposta, na conversa: ✓ enviada e ✓✓ azul lida. A resposta conta como lida quando o visitante está com o chat aberto na conversa e a página do seu site à vista. O visitante não vê esses tiques.
• Quero tirar o chat do ar. Clique no chip "No ar" no topo da tela do canal; ele vira "Fora do ar" e o widget para de responder.
• Mudei as boas-vindas e nada aconteceu. Com agente de IA ou fluxo vinculado, a abertura é a saudação deles, não a do canal.
• A conversa não chegou para ninguém. Com agente ou fluxo atendendo, a conversa só entra na fila humana quando o bot transfere. Só com a equipe, a conversa entra sem fila definida: confira a regra em Administração › Configurações › Atendimento › Produtividade › Roteamento de chamados e, se não houver, procure a conversa em Atendimento › Conversas pelo botão Atender próximo.