Integrar minichat com meu site

​

Visão Geral

Como instalar o Minichat no seu site ou aplicação web. O processo inclui a adição de código HTML e CSS ao seu site e o registro de seus domínios para uso autorizado.

​

Código de Instalação

Coloque o código abaixo antes da tag </body>. O bloco de configuração deve vir antes do script principal:

<script>
  window.tolky = window.tolky || {
    config: {
      slug: "SLUG_DO_AVATAR",
    },
  };
</script>
<script type="module" src="https://minichat.tolky.to/main.js" async></script>

• SLUG_DO_AVATAR: é o identificador do avatar — o mesmo nome usado em https://tolky.to/slug_do_avatar

​

Isolamento de CSS

O widget é encapsulado em Shadow DOM. Isso significa que:

• O CSS do seu site não afeta a aparência do widget.
• O CSS do widget não vaza para o seu site.

Se o seu site usa classes genéricas como .message, .image, .audio, .video ou .chat-container, elas convivem sem interferência com a renderização interna do widget.

​

Opções de Configuração

​

Aparência do botão flutuante

Enquanto o chat está fechado, o widget aparece como um cartão quadrado num canto da tela: a imagem do avatar com uma etiqueta de convite embaixo. Quatro opções controlam esse cartão.

Todas as opções são opcionais e os padrões reproduzem o visual atual — se você não informar nenhuma delas, nada muda no seu site.

​

Tamanho

O cartão é quadrado — a altura acompanha a largura. Tudo que fica dentro dele (imagem, etiqueta, ícone, aviso de mensagem nova e o arredondamento das bordas) cresce e diminui junto, mantendo a proporção.

Valores fora dos limites são ajustados para o limite mais próximo. Um valor que não seja reconhecido cai no tamanho padrão e registra um aviso no console do navegador.

​

Etiqueta de convite

showCtaTextDesktop e showCtaTextMobile controlam a etiqueta arredondada com o texto de convite. Com false, a etiqueta some e o cartão fica só com a imagem — continuando clicável, e o aviso de mensagem nova continua aparecendo sobre ele.

As duas opções são independentes: dá para manter a etiqueta no desktop e removê-la no mobile.

<script>
  window.tolky = window.tolky || {
    config: {
      slug: "SLUG_DO_AVATAR",
      iconSizeDesktop: "large",
      iconSizeMobile: 72,
      showCtaTextMobile: false,
    },
  };
</script>

​

Posição do botão flutuante

O visitante escolhe onde o botão fica, e a escolha é lembrada no navegador dele:

• Arrastar: segurar o botão e soltar em qualquer lugar da tela. Ele encaixa sozinho na posição mais próxima entre nove (três colunas × três linhas). Funciona com mouse no desktop e com o dedo no mobile.
• Menu de posições (só no desktop): passando o mouse sobre o botão aparece um ícone de três pontos no canto superior direito. Ele abre um mapa da tela em que basta clicar na posição desejada.

O botão começa no canto inferior direito.

​

Fixar o chat na lateral

No desktop, com uma conversa já iniciada, aparece um botão no topo do chat que fixa o chat como uma barra lateral: o chat ocupa a lateral inteira da janela e o conteúdo do seu site é empurrado para o lado, em vez de ficar coberto. O mesmo botão desfaz.

O lado escolhido acompanha a posição atual do botão flutuante — se ele estiver à esquerda, o chat fixa à esquerda.

​

Pré-formulário

Com preForm: true, antes da primeira mensagem o chat mostra um formulário curto de identificação:

Ao enviar, os dados viram a primeira mensagem da conversa e o visitante segue direto para o chat. A identificação fica registrada no navegador, então o formulário não reaparece a cada recarga.

<script>
  window.tolky = window.tolky || {
    config: {
      slug: "SLUG_DO_AVATAR",
      preForm: true,
    },
  };
</script>

​

Tema

Sem configuração, o widget acompanha o tema do sistema do visitante e troca sozinho se ele mudar de claro para escuro durante a navegação. Para fixar um dos dois, use theme:

<script>
  window.tolky = window.tolky || {
    config: {
      slug: "SLUG_DO_AVATAR",
      theme: "dark",
    },
  };
</script>

​

Apontando para outro ambiente

Por padrão, o widget se conecta ao minichat de produção (https://minichat.tolky.to). Para apontar o widget para um ambiente diferente (homologação, desenvolvimento), troque a URL no <script> para o ambiente correspondente e defina socketUrl com o mesmo valor.

Exemplo apontando para staging:

<script>
  window.tolky = window.tolky || {
    config: {
      slug: "SLUG_DO_AVATAR",
      socketUrl: "https://mini-chat.stg.tolky.to",
    },
  };
</script>
<script type="module" src="https://mini-chat.stg.tolky.to/main.js" async></script>

​

Conversa em tempo real (WebSocket)

Quando o usuário envia a primeira mensagem, o widget abre uma conexão WebSocket com o backend Tolky (api.tolky.to em produção) e entra na “room” daquela conversa específica. Isso é o que permite receber respostas da IA e mensagens do gestor em tempo real, sem refresh.

​

Indicador visual de status

Ao lado do nome do avatar, no topo do chat, aparece uma pequena bolinha indicando o estado da conversa em tempo real. O indicador só fica visível depois que a primeira mensagem é enviada — antes disso não há conversa, e portanto nada para indicar.

Passar o mouse sobre o indicador exibe um tooltip com a descrição do estado.

​

Requisitos de rede

A conexão usa wss:// (WebSocket sobre TLS). Se o seu site está atrás de um firewall corporativo ou proxy:

• Permita wss://api.tolky.to (ou a URL equivalente do ambiente que você usa).
• Permita também https://api.tolky.to/socket.io/socket.io.js (script carregado dinamicamente para inicializar o cliente Socket.IO).
• Se o seu site usa Content Security Policy, configure as diretivas abaixo:

​

Solução de problemas

O indicador fica laranja indefinidamente:

• Verifique no DevTools (aba Network → WS) se há um handshake em /socket.io/?EIO=... retornando 200.
• Confirme que wss://api.tolky.to (ou a URL do seu ambiente) não está bloqueado por proxy/firewall.
• Veja o console do navegador: o cliente loga [tolky socket] em todos os eventos relevantes.

O indicador nunca aparece (mesmo após enviar mensagem):

• O ambiente que serve o main.js não foi compilado com a URL do servidor de socket. Confirme a URL no <script> e o socketUrl no window.tolky.config.

​

Envio de anexos

O usuário pode enviar arquivos junto com a mensagem clicando no ícone de clipe ao lado do campo de texto. O arquivo é interpretado pela IA multimodal para responder com base no conteúdo (ex: descrever uma imagem, resumir um PDF).

​

Tipos e limites

​

Comportamento

• O preview do arquivo aparece acima do campo de texto e pode ser removido pelo botão ”×” antes do envio.
• O envio usa multipart/form-data e roteia pelo servidor do minichat antes de chegar ao backend Tolky — o site host não precisa configurar nada especial além do CSP img-src mencionado acima.
• A URL pública do anexo é incluída no histórico da conversa como markdown de imagem, e renderizada inline para imagens.

​

Restrições do navegador

• O <input type="file"> precisa de gesto do usuário para abrir o seletor — não é possível abrir programaticamente sem clique.
• Em navegadores antigos sem suporte a URL.createObjectURL, o preview não aparece, mas o upload ainda funciona.

​

Download de mídia

Mensagens com mídia (imagem, áudio ou vídeo) — sejam enviadas pelo usuário, pela IA ou pelo gestor — exibem um botão de download circular no canto inferior direito da bolha. O clique baixa o arquivo original (não a versão comprimida do preview).

Para documentos (PDFs), o botão de download já vem como parte do componente nativo, ao lado do nome do arquivo.

​

Indicador “digitando”

Quando o usuário envia uma mensagem, três pontinhos animados aparecem indicando que o avatar está pensando. Detalhes do comportamento:

• Delay de 4 segundos: os pontinhos só aparecem se a resposta demorar mais de 4 s. Respostas rápidas não acionam o indicador, evitando “flash” desnecessário.
• Conversa pausada (atendimento humano): quando a conversa está em modo is_paused = true (gestor assumiu o atendimento), os pontinhos nunca aparecem — não há IA pensando para indicar.
• O indicador desaparece automaticamente assim que qualquer mensagem do avatar/gestor chega, seja via socket ou via resposta da requisição.

​

Persistência da conversa

O widget mantém a conversa entre recargas da página (F5, navegação para outra página do site, fechamento e reabertura do navegador).

​

Como funciona

• Após a primeira mensagem, o widget guarda o identificador da conversa e o do contato em localStorage (chaves tolky-minichat-conversation-id e tolky-minichat-lead-id).
• Em cada nova carga, o widget chama GET /api/v1/conversation/{leadId} no servidor do minichat (que proxia para o backend Tolky), recebe o histórico completo + estado da conversa e renderiza imediatamente — sem o usuário precisar começar do zero.
• Ao reabrir o widget (clicar no X para fechar e depois reabrir), o widget refaz o mesmo GET e atualiza o histórico — mesmo efeito de um F5. Cobre mensagens novas que possam ter chegado enquanto o chat estava fechado.
• O estado de pausa (is_paused) também é restaurado, então o indicador de digitando volta a respeitar o modo de atendimento humano sem precisar esperar uma nova mensagem.
• Se a conversa salva não existir mais (foi deletada/expirou), o localStorage é limpo automaticamente e o usuário cai no fluxo de boas-vindas normal. Erros de rede preservam o localStorage para nova tentativa.

​

Chaves usadas no navegador

Em localStorage (sobrevivem ao fechamento do navegador):

Em sessionStorage (duram enquanto a aba estiver aberta):

​

Aviso de mensagem nova

Com o chat fechado, cada mensagem que chega acende uma bolinha vermelha com o contador de não lidas sobre o botão flutuante. O contador zera quando o visitante abre o chat, e mostra 99+ acima de noventa e nove.

​

Modo privado/incognito

Em janelas privadas o localStorage pode estar desabilitado ou ser efêmero — nesses casos o comportamento é “começar do zero a cada carga”. O widget detecta isso silenciosamente e não falha.

​

API JavaScript

Após a inicialização, o widget expõe métodos em window.tolky para controle programático:

// Abre o painel de chat
window.tolky.show();

// Fecha o painel de chat (volta para o botão)
window.tolky.hide();

// Torna o widget visível na página
window.tolky.open();

// Remove o widget completamente da página
window.tolky.close();

// Envia uma mensagem programaticamente (abre o chat automaticamente)
window.tolky.sendMessage("Olá, preciso de ajuda!");

​

Exemplo: Abrir o chat ao clicar em um botão customizado

document.getElementById("meu-botao").addEventListener("click", () => {
  window.tolky.show();
});

​

Exemplo: Enviar uma mensagem ao entrar na página

window.addEventListener("load", () => {
  window.tolky.sendMessage("Quero saber sobre planos e preços");
});

​

Inicialização em SPAs (React, Vue, Angular)

O widget inicia sozinho no load da página. Se o script for inserido depois que a página já carregou — o caso mais comum em Single Page Applications, e também quando se adia o carregamento para ganhar performance — esse evento já passou e o widget não inicia. Nesses casos, dispare loadingMinichat manualmente:

window.dispatchEvent(new Event("loadingMinichat"));

Exemplo carregando o widget só na primeira interação do visitante, para não competir com o carregamento inicial da página:

function carregarMinichat() {
  if (document.querySelector("script[data-tolky-minichat]")) return;

  window.tolky = window.tolky || {};
  window.tolky.config = { slug: "SLUG_DO_AVATAR" };

  const script = document.createElement("script");
  script.type = "module";
  script.src = "https://minichat.tolky.to/main.js";
  script.dataset.tolkyMinichat = "true";
  script.addEventListener("load", () => {
    window.dispatchEvent(new Event("loadingMinichat"));
  });
  document.body.appendChild(script);
}

["pointerdown", "keydown", "touchstart", "scroll"].forEach((evento) =>
  window.addEventListener(evento, carregarMinichat, { once: true, passive: true })
);
setTimeout(carregarMinichat, 6000); // garante o carregamento para quem não interage

​

Liberação de Domínios

Para garantir segurança e uso exclusivo do Minichat, é necessário registrar os domínios autorizados.

​

Como Registrar os Domínios

Envie um e-mail para admin@tolky.to com as seguintes informações:

Assunto do E-mail: Liberação de Domínios

Mensagem do E-mail: Deve conter a lista dos domínios que terão permissão para usar o minichat. Exemplo de formato:

Eu autorizo o acesso ao minichat para os domínios a seguir:
- http://meudominio1.com.br
- http://meudominio2.com.br

Depois disso, o Minichat estará ativo no seu site.