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

​

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

No topo do chat, ao lado do botão de fechar, 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 conversationId em localStorage (chave tolky-minichat-conversation-id).
• Em cada nova carga, o widget chama GET /api/v1/conversation/{id} 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 em localStorage

​

Como encerrar e começar uma conversa nova

O usuário pode encerrar a conversa diretamente pelo widget, sem precisar de reload.

• Pela UI: enquanto há uma conversa ativa, aparece um botão circular no header (ao lado do X de fechar) com ícone de “recomeçar”. Ao clicar, o widget pede confirmação e, se aceito, descarta a conversa atual e volta para a tela de boas-vindas.
• Programaticamente: chame window.tolky.endConversation() (também disponível na API JavaScript).

O encerramento limpa apenas o tolky-minichat-conversation-id e sai da room do socket — a tolky-minichat-session (identidade anônima do navegador) é mantida, então o backend continua reconhecendo o mesmo usuário, só com uma conversa nova.

​

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!");

// Encerra a conversa atual e volta para a tela de boas-vindas (sem reload).
// Mantém a identidade anônima do navegador — só zera o thread da conversa.
window.tolky.endConversation();

​

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)

Em Single Page Applications onde o window.onload pode não ser re-disparado após navegação, use o evento loadingMinichat para inicializar o widget manualmente:

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

​

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.