Até agora, o widget de chat do Kookee tinha um pré-requisito que ninguém pediu: React.
Para quem já usa React, tudo bem. Mas um site institucional em WordPress, uma loja no Shopify, uma documentação feita com gerador de sites estáticos ou um app em Vue ou Angular ficavam de fora. O widget respondia a perguntas com base nos seus artigos de ajuda, e o único jeito de tê-lo era usar o framework certo.
Esse pré-requisito acabou. Agora o widget de chat vem como uma simples tag de script.
Uma linha
<script async src="https://kookee.dev/chat/latest.js" data-api-key="YOUR_API_KEY"></script>Cole isso antes de </body> e você tem um assistente flutuante que responde com base nos artigos publicados da sua central de ajuda. Sem npm install, sem build, sem configurar bundler, sem framework.
Duas coisas precisam estar certas antes de funcionar:
O código pronto, já com a sua chave, fica na página Widget do site do seu projeto, no painel. Copie de lá em vez de digitar a URL à mão.
Adicione o domínio do seu site às Origens permitidas do projeto. Assim que a lista deixa de estar vazia, as requisições de qualquer outro lugar são recusadas. É isso que impede alguém de copiar a sua chave do código-fonte da página e rodar o seu assistente no próprio site.
Um domínio que falta nessa lista é o motivo mais comum de o balão aparecer e todas as perguntas falharem. Se as respostas nunca chegam, confira primeiro a lista de origens.
De onde vêm as respostas
O widget se baseia nos seus artigos de ajuda publicados. Ele busca neles por significado e por palavra-chave, responde em linguagem natural e cita os artigos que usou, para o leitor abrir a fonte.
Isso pesa mais do que parece. Um assistente que responde com base na sua documentação fica limitado a ela: diz aos usuários o que você de fato escreveu. Quando ele não sabe responder, você descobre uma lacuna concreta, em vez de ver um modelo genérico inventar um recurso que o seu produto não tem.
Personalizar o visual
Tudo o que é visual é um atributo data-*, então quem não é desenvolvedor ajusta o widget editando uma linha do template da página:
<script
async
src="https://kookee.dev/chat/latest.js"
data-api-key="YOUR_API_KEY"
data-title="Suporte"
data-greeting="Oi! Pergunte o que quiser sobre o produto."
data-placeholder="Digite sua pergunta…"
data-launcher-label="Precisa de ajuda?"
data-position="bottom-left"
data-theme="auto"
data-primary-color="#ff6b00"
></script>data-position aceita bottom-right ou bottom-left, data-theme aceita light, dark ou auto, e data-locale escolhe o idioma. data-base-url serve para apontar o widget para outro host de API.
O widget é renderizado dentro de um shadow root, e é isso que torna seguro colá-lo num site que você não construiu. O CSS da sua página não vaza para dentro nem muda o visual do chat, e o CSS do chat não vaza para fora nem quebra o seu layout. Um tema do Shopify com seletores globais agressivos não chega até ele.
A API em JS, para quando os atributos não bastam
Os atributos cobrem o caso comum. Quando você quer o assistente ligado à sua própria interface, existe o window.KookeeChat:
KookeeChat.open();
KookeeChat.close();
KookeeChat.toggle();
KookeeChat.sendMessage('Como faço para redefinir minha senha?');
KookeeChat.clearMessages();Assim, o link “Falar com o suporte” que você já tem abre o assistente em vez do cliente de e-mail:
document.querySelector('#support-link').addEventListener('click', (event) => {
event.preventDefault();
KookeeChat.open();
});Eventos funcionam como assinaturas, e cada assinatura retorna a própria função para cancelá-la:
const unsubscribe = KookeeChat.on('sourceClick', (source) => {
analytics.track('help_article_opened', { slug: source.slug });
});on() também aceita open e close. E se você quer controle total da configuração, sem atributos, chame init() você mesmo: ele aceita tudo o que os atributos aceitam, e mais algumas coisas que eles não conseguem expressar:
KookeeChat.init({
apiKey: 'YOUR_API_KEY',
greeting: 'Em que posso ajudar?',
suggestions: ['Como eu começo?', 'Quais são os planos e preços?', 'Como faço para cancelar?'],
hideLauncher: true,
zIndex: 9999,
offset: { x: 24, y: 96 },
onSourceClick: (source) => window.open(`/help/${source.slug}`, '_blank'),
onOpenChange: (isOpen) => console.log('chat open:', isOpen),
});Vale a pena definir suggestions. Perguntas iniciais fazem a diferença entre um usuário que digita alguma coisa e um usuário que encara o campo vazio e decide que vai mandar um e-mail. hideLauncher desliga o balão padrão, para você abrir o widget pelo seu próprio botão, e destroy() desmonta tudo de novo. Isso serve numa single-page app quando o usuário entra numa área onde o assistente não deve aparecer.
Para TypeScript, as tipagens estão em https://kookee.dev/chat/latest.d.ts.
Detalhes que aparecem no uso real
A conversa sobrevive à navegação entre páginas na mesma aba: quem pergunta algo na página de preços e depois vai para a de recursos não perde o fio. Minimizar também mantém a conversa; só o botão Novo chat a apaga. Há um modo expandido, com a altura toda da tela, para respostas mais longas, e quem prefere ver só o balão pode fechar a etiqueta de texto ao lado dele.
Nada disso é uma opção que você precisa configurar. São esses detalhes que fazem o widget não parecer um iframe enxertado na página.
Se você já usa React
Nada muda:
import { KookeeChatWidget } from '@kookee/react/chat';Num app React, esse componente continua sendo a escolha certa: ele fica dentro da sua árvore e recebe props como qualquer outro componente. A tag de script não o substitui. Ela é a resposta para o grupo bem maior de sites que nunca instalariam um pacote React só para ter um balão de chat, e agora não precisam.