Hasta ahora, el widget de chat de Kookee tenía un requisito que nadie había pedido: React.
No es un problema si ya usas React. Pero si tu sitio de marketing está hecho con WordPress, tu tienda con Shopify, tu documentación con un generador de sitios estáticos o tu aplicación con Vue o Angular, queda descartado. El widget respondía preguntas a partir de tus artículos de ayuda, y la única forma de tenerlo era usar el framework adecuado.
Ese requisito ya no existe. El widget de chat ahora se distribuye como una simple etiqueta script.
Una línea
<script async src="https://kookee.dev/chat/latest.js" data-api-key="YOUR_API_KEY"></script>Pégala antes de </body> y tendrás un asistente flotante que responde a partir de los artículos publicados de tu centro de ayuda. Sin npm install, sin paso de compilación, sin configurar un bundler, sin framework.
Para que funcione, revisa dos cosas:
El fragmento de código real, con tu clave ya incluida, está en la página Widget del sitio de tu proyecto, en el panel. Cópialo de ahí en lugar de escribir la URL a mano.
Añade el dominio de tu sitio a la lista Orígenes permitidos del proyecto. En cuanto la lista tiene algún dominio, se rechazan las solicitudes de cualquier otro sitio. Eso impide que alguien copie tu clave del código fuente de la página y use tu asistente en su propio sitio.
Un dominio que falta en esa lista es la causa más habitual de que aparezca la burbuja pero fallen todas las preguntas. Si las respuestas nunca llegan, revisa primero la lista de orígenes.
Qué responde en realidad
El widget se basa en los artículos de ayuda que publicaste. Los busca tanto por significado como por palabras clave, responde en lenguaje natural y cita los artículos que usó, para que el lector pueda abrir la fuente.
Esto importa más de lo que parece. Un asistente que responde a partir de tu documentación está limitado por tu documentación: les dice a los usuarios lo que de verdad escribiste, y cuando no sabe responder, descubres un hueco concreto en ella, en lugar de ver cómo un modelo de propósito general se inventa una función que tu producto no tiene.
Personalízalo
Todo lo visual se controla con atributos data, así que alguien que no programa puede ajustar el widget editando una línea de la plantilla de la página:
<script
async
src="https://kookee.dev/chat/latest.js"
data-api-key="YOUR_API_KEY"
data-title="Soporte"
data-greeting="¡Hola! Pregúntame lo que quieras sobre el producto."
data-placeholder="Escribe tu pregunta…"
data-launcher-label="¿Necesitas ayuda?"
data-position="bottom-left"
data-theme="auto"
data-primary-color="#ff6b00"
></script>data-position acepta bottom-right o bottom-left, data-theme acepta light, dark o auto, y data-locale elige el idioma. data-base-url sirve para apuntar el widget a otro host de la API.
El widget se renderiza dentro de un shadow root, y por eso se puede pegar sin riesgo en un sitio que no hiciste tú. El CSS de tu página no puede colarse y cambiar el estilo del chat, y el CSS del chat no puede salirse y romper tu maquetación. Un tema de Shopify con selectores globales agresivos no lo toca.
La API de JavaScript, para cuando no bastan los atributos
Los atributos cubren el caso habitual. Cuando quieras conectar el asistente con tu propia interfaz, tienes window.KookeeChat:
KookeeChat.open();
KookeeChat.close();
KookeeChat.toggle();
KookeeChat.sendMessage('¿Cómo restablezco mi contraseña?');
KookeeChat.clearMessages();Así, tu enlace «Contactar con soporte» puede abrir el asistente en lugar del cliente de correo:
document.querySelector('#support-link').addEventListener('click', (event) => {
event.preventDefault();
KookeeChat.open();
});Los eventos son suscripciones, y cada una devuelve su propia función para cancelarla:
const unsubscribe = KookeeChat.on('sourceClick', (source) => {
analytics.track('help_article_opened', { slug: source.slug });
});on() también acepta open y close. Y si prefieres controlar toda la configuración en lugar de usar atributos, llama tú mismo a init(): acepta todo lo que aceptan los atributos y algunas cosas que con ellos no se pueden expresar:
KookeeChat.init({
apiKey: 'YOUR_API_KEY',
greeting: '¿En qué te puedo ayudar?',
suggestions: ['¿Cómo empiezo?', '¿Qué planes de precios hay?', '¿Cómo cancelo?'],
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 la pena configurar suggestions. Las preguntas de inicio marcan la diferencia entre un usuario que escribe algo y uno que se queda mirando un campo vacío y decide que mejor te manda un correo. hideLauncher quita la burbuja predeterminada para que abras el widget desde tu propio botón, y destroy() lo desmonta todo otra vez. Sirve en una aplicación de una sola página cuando el usuario inicia sesión y entra en una zona donde el asistente no tiene sentido.
Si usas TypeScript, los tipos están en https://kookee.dev/chat/latest.d.ts.
Detalles que se notan en el uso real
La conversación se mantiene al navegar entre páginas dentro de la pestaña, así que un usuario que pregunta en tu página de precios y luego pasa a la de funciones no pierde el hilo. Al minimizar, la conversación también se conserva: solo el botón Nuevo chat la borra. Hay un modo expandido a toda altura para las respuestas largas, y la etiqueta junto a la burbuja se puede cerrar si el usuario prefiere ver solo la burbuja.
Nada de esto son opciones que tengas que configurar. Son las razones por las que el widget no parece un iframe metido a la fuerza.
Si ya usas React
No cambia nada:
import { KookeeChatWidget } from '@kookee/react/chat';Ese componente sigue siendo la opción correcta en una aplicación React: vive dentro de tu árbol y recibe props como cualquier otro componente. La etiqueta script no lo sustituye. Es la respuesta para el grupo, mucho más grande, de sitios que nunca iban a instalar un paquete de React para tener una burbuja de chat, y que ahora no tienen por qué hacerlo.