Widget para tu sitio web

El widget es el chat que los visitantes ven en tu sitio web. Carga el bot que publicaste y gestiona toda la conversación en el navegador. Sin modelo de lenguaje, sin solicitudes a terceros y con un tamaño de unos 22KB tras la compresión. El chat con un agente se carga desde un archivo independiente, solo cuando lo activas.

Instalación

Pega esta línea antes de </body> en cada página donde deba aparecer el bot. El panel de control la muestra con tu clave en la página Instalación.

<script src="https://cdn.kavchat.com/v1/kavchat.js" data-key="pk_live_..." async></script>

Puedes incluir la clave pública (pk_live_...) en la página. Nunca incluyas la clave secreta (sk_live_...) en una página.

Atributos

<script
  src="https://cdn.kavchat.com/v1/kavchat.js"
  data-key="pk_live_..."
  data-locale="he"
  data-user-token="<identity JWT>"
  data-user-name="Dana"
  data-open="false"
  async></script>

API de JavaScript

El script instala window.Kavchat:

Kavchat.init({
  publicKey: 'pk_live_...',
  apiBase: 'https://api.kavchat.com', // optional
  locale: 'he',                       // optional
  userToken: '<identity JWT>',        // optional
  userName: 'Dana',                   // optional
  open: false,                        // optional
  onScreen(screen, targetId) {},      // optional: "screen" buttons in your scripts
  onEvent(event) {},                  // optional: ready, unavailable, open, close, effect, ticket
});
Kavchat.open();
Kavchat.close();
Kavchat.toggle();
Kavchat.setUser({ token: '<identity JWT>', name: 'Dana' }); // on login; setUser(null) on logout
Kavchat.offset({ bottom: 80 });       // lift the launcher, e.g. above a cookie banner; offset(null) resets
Kavchat.destroy();

No necesitas init si la etiqueta del script incluye data-key. Una nueva llamada a init reemplaza el widget en ejecución.

Llamar a la API antes de que se cargue el script

La etiqueta del script es async, así que tu código podría ejecutarse antes. Crea una cola y añade las llamadas: el widget las ejecutará en orden cuando se cargue. init siempre se ejecuta primero y su configuración tiene prioridad sobre los atributos de la etiqueta.

<script>
  window.Kavchat = window.Kavchat || { q: [] };
  Kavchat.q.push(['init', { publicKey: 'pk_live_...', onScreen: function (s, id) { location.href = '/' + s + '/' + id; } }]);
  Kavchat.q.push(['setUser', { token: '<identity JWT>', name: 'Dana' }]);
</script>
<script src="https://cdn.kavchat.com/v1/kavchat.js" async></script>

Cada elemento de la cola es [methodName, ...args]. Una vez cargado el script, Kavchat.q.push(...) sigue funcionando y ejecuta la llamada de inmediato, así que el mismo código sirve para ambos casos.

Espacio para el banner de cookies

Si tu sitio tiene un elemento fijo en la parte inferior de la pantalla, como un banner de cookies, puedes desplazar el botón, la ventana y las burbujas para situarlos por encima. Hay dos formas de hacerlo: con la variable CSS --kavchat-bottom o con el comando Kavchat.offset, que acepta un número en píxeles o un valor de longitud como 5rem. El desplazamiento se suma a la altura configurada en el panel de administración. Cuando se cierre el banner, elimina la variable o llama a offset(null). Ambas opciones funcionan también en sitios con una CSP estricta. En el móvil, la ventana se abre a pantalla completa y no se desplaza.

/* while your cookie banner is shown */
body.cookie-banner-open { --kavchat-bottom: 80px; }

// works before or after the widget script loads
window.Kavchat = window.Kavchat || { q: [] };
Kavchat.q.push(['offset', { bottom: banner.offsetHeight + 12 }]);

// after the visitor makes a choice
Kavchat.q.push(['offset', null]);

Eventos

La función onEvent recibe uno de los siguientes eventos:

Kavchat.init({
  publicKey: 'pk_live_...',
  onEvent(event) {
    if (event.type === 'ready') console.log('Bot version', event.version, event.offline ? '(offline copy)' : '');
    if (event.type === 'ticket') console.log('Request opened', event.number);
  },
});

Acciones del guion

• Contacto: abre el formulario de contacto dentro del chat. La transcripción de la conversación se adjunta al ticket.
• Enlace: abre enlaces https: y tel: en una pestaña nueva (rel="noopener noreferrer"). Los demás tipos de enlaces no se abren.
• Pantalla: llama a tu función onScreen(screen, targetId). Sin ella, el botón no hace nada en el sitio web.

Lista de pantallas en el editor

Declara una sola vez las pantallas que tu aplicación puede abrir en la opción screens de Kavchat.init. El SDK envía la lista a Kavchat automáticamente, y el editor de guiones ofrece esas pantallas por su nombre en una lista desplegable, en lugar de un campo de texto libre. El editor también pide un identificador de elemento cuando la pantalla lo necesita y advierte si un botón lleva a una pantalla no declarada. Nadie tiene que escribir manualmente la lista de pantallas en el panel de control.

Kavchat.init({
  publicKey: 'pk_live_...',
  screens: [
    { id: 'orders', label: 'My orders' },
    { id: 'product', label: 'Product page', needsTarget: true }, // the button also carries a product id
  ],
  onScreen(screen, targetId) {
    location.href = targetId ? `/${screen}/${targetId}` : `/${screen}`;
  },
});

• id es el valor que recibe onScreen: letras latinas, dígitos, _, . y -, hasta 40 caracteres. label es el nombre que ve el administrador, hasta 60 caracteres. Se permiten hasta 100 pantallas. Se omiten las entradas no válidas y los identificadores duplicados.
• needsTarget: el botón también incluye un identificador de elemento (por ejemplo, el de un producto), que llega a onScreen como targetId.
• La lista se envía en segundo plano después de cargar la versión, solo si ha cambiado o una vez por semana. Si el envío falla, no se muestra ningún aviso y se vuelve a intentar en el siguiente inicio. El usuario no ve nada.
• Las pantallas registradas aparecen en el panel de control, en Bot, Configuración, "Pantallas de la aplicación", junto con las plataformas que han informado de cada pantalla. Desde ahí puedes eliminar una pantalla que hayas quitado de la aplicación.

Identificación de tus usuarios

Para asociar tu identificador de usuario a las conversaciones y los tickets, o mostrar el bot solo a usuarios de prueba, firma un JWT en el servidor y pásalo mediante data-user-token o userToken. Cuando el usuario inicie o cierre sesión, llama a Kavchat.setUser(...). El widget envía el token en la cabecera Authorization: Bearer <token> en cada llamada, y los usuarios que han iniciado sesión pueden crear un ticket sin dejar un correo electrónico ni un teléfono. Para saber cómo crear el token, consulta Identificación de usuarios.

Política CSP

El widget funciona en sitios con una CSP estricta, sin 'unsafe-inline' ni 'unsafe-eval'. Basta con que autorices nuestros dos orígenes:

script-src https://cdn.kavchat.com;
connect-src https://api.kavchat.com;

Los estilos se cargan como constructable stylesheets dentro del Shadow DOM, por lo que no es necesario modificar style-src. Si el bot tiene una imagen propia o hay imágenes en los guiones, añade a img-src el servidor desde el que se cargan. El widget no carga nada desde otros orígenes ni abre un iframe.

Chat con un agente

No necesitas configurar nada en tu sitio web. Cuando activas el chat con agentes en el panel de administración, el widget carga un archivo adicional, kavchat-live.js, desde la misma carpeta y con la misma versión que kavchat.js. Los sitios sin chat con agentes no descargan este archivo.

• La opción: junto a "Contactar al equipo" aparece la opción "Hablar con un agente", solo después de que el servidor confirme que hay un agente disponible. Fuera del horario de atención, o cuando todos los agentes están ocupados, solo se muestra el formulario de contacto. A su lado aparece una breve explicación y, si se sabe, cuándo volverá a estar disponible el equipo. Cuando se agota la cuota mensual, el formulario se muestra sin explicación.
• La solicitud: los visitantes sin sesión iniciada dejan un correo electrónico o un teléfono, por si ningún agente queda disponible a tiempo. También pueden añadir un nombre y un primer mensaje. Si hay más de un departamento abierto, eligen uno. Los usuarios identificados (userToken) no necesitan completar los datos de contacto. Si ningún agente puede atender la conversación, se abre el formulario de contacto con los datos ya introducidos.
• La espera: se muestra "Esperando a un agente" con una cuenta regresiva hasta que termine el tiempo de espera que hayas configurado, y los botones "Dejar un mensaje en su lugar" y "Finalizar conversación". El visitante puede escribir mientras espera. Cuando se agota el tiempo, la conversación se convierte automáticamente en un ticket. El visitante ve el número del ticket y una explicación de que ningún agente quedó disponible a tiempo.
• La conversación: nombre del agente, mensajes, indicador de escritura, transferencia a otro agente y finalización de la conversación. Todo lo que llega del servidor se muestra como texto sin formato, sin HTML ni enlaces. Los lectores de pantalla anuncian los mensajes nuevos y, cuando la ventana está cerrada, aparece un punto en el botón flotante.
• Tiempo real: la conexión se realiza mediante Server-Sent Events. Si se interrumpe, el widget intenta reconectarse a intervalos cada vez mayores y recupera todo lo que no haya recibido. Así, ningún mensaje se pierde ni aparece dos veces. En redes que bloquean esta conexión, el widget pasa a realizar consultas repetidas (long-poll). Cada mensaje tiene un identificador, por lo que un reintento no genera duplicados. Los mensajes que no se han enviado quedan marcados y se pueden reenviar con un toque.
• Recarga: la credencial de acceso a la conversación se guarda en localStorage según la clave pública y la conversación, nunca en la URL. Es válida durante un máximo de 12 horas o hasta que termine la conversación. Así, al recargar o pasar a otra página, se restaura toda la conversación: primero la parte con el bot y después la parte con el agente.
• Sin preflight: las llamadas se envían sin cabeceras especiales, y el cuerpo de la solicitud es JSON enviado como text/plain.

Respuestas de IA (Premium)

No necesitas configurar nada en tu sitio web. Cuando activas las respuestas de IA en el panel de administración (con tu propia clave de un proveedor de IA), las preguntas que ningún guion puede responder se envían a Kavchat. Durante la espera, de hasta 20 segundos, el chat muestra que el bot está escribiendo. La respuesta se muestra como texto sin formato con una pequeña etiqueta "Respuesta de IA" en el idioma de la interfaz. Debajo aparecen un botón para un tema relacionado, si lo hay, y el botón "Contactar al equipo".

Si no hay respuesta, o si la solicitud falla, tarda demasiado o supera el límite (10 respuestas por conversación cada 15 minutos), el chat muestra el mensaje habitual "No encontré una respuesta". La pregunta sigue apareciendo en el informe de preguntas sin respuesta, y las respuestas de IA se guardan en la conversación como cualquier otro mensaje.

Cómo se comporta el widget

• Aislamiento: todo se muestra dentro de un Shadow DOM. Tu CSS no afecta al widget y el CSS del widget no afecta a la página.
• Caché: el bot publicado se guarda en localStorage según la clave pública, junto con su ETag. En cada carga se envía la cabecera If-None-Match y, si no ha cambiado nada, el servidor responde con 304. Cuando no hay conexión, el widget usa la copia guardada y muestra un aviso.
• Conversaciones: se guarda un identificador aleatorio de conversación en sessionStorage, de modo que al cambiar de página se mantiene la misma conversación.
• Chat con un agente: una conversación abierta se guarda en localStorage y se restaura en la siguiente página.
• Datos: el recorrido de la conversación se comunica unos 2 segundos después de cada acción y también cuando se oculta la página.
• Insignia de Kavchat: se muestra en todos los planes. En Premium puedes ocultarla en la configuración del bot.
• Accesibilidad: la ventana es un cuadro de diálogo con una etiqueta; el foco se mueve a ella y vuelve al elemento anterior al cerrarla; Esc la cierra; los botones son botones reales; los mensajes nuevos del bot se leen en voz alta, y las animaciones se reducen cuando el visitante lo ha solicitado.

Instalación desde npm

En una aplicación de página única puedes empaquetar el widget con tu código en lugar de cargar la etiqueta del script:

yarn add @kavchat/widget
# or: npm install @kavchat/widget

import { createWidget } from '@kavchat/widget';

const widget = createWidget({ publicKey: 'pk_live_...' });
await widget.ready;
widget.open();