kairo-agents

Widget de chat para el navegador con soporte de menús guiados, migas de navegación, multimedia y transporte HTTP configurable. Integración nativa con la plataforma Kairo y compatible con cualquier backend propio.

Instalación

npm install kairo-agents

Importar estilos

Agrega el CSS del widget en tu entrada principal (o en tu HTML):

import "kairo-agents/styles.css";

<!-- o directamente en HTML -->
<link rel="stylesheet" href="node_modules/kairo-agents/dist/kairo-agents.css" />

Uso básico — backend propio

import { createChatWidget, createHttpTransport } from "kairo-agents";
import "kairo-agents/styles.css";

const transport = createHttpTransport({
  url: "https://tu-servidor.com/chat",
});

const { chat, open, close, destroy } = createChatWidget(
  document.getElementById("chat-container"),
  {
    transport,
    title: "Asistente",
    placeholder: "Escribe un mensaje…",
    placement: "bottom-right", // "bottom-left" | "top-left" | "top-right" | "inline"
    colorScheme: "auto",       // "light" | "dark" | "auto"
  }
);

// Abrir o cerrar el widget programáticamente
open();
close();

// Limpiar cuando no se necesite más
destroy();

Uso con la plataforma Kairo

import { KairoChat } from "kairo-agents";
import "kairo-agents/styles.css";

const kairo = new KairoChat({
  baseUrl: "https://api.kairo.com",
  widgetToken: "TU_TOKEN",
  container: document.getElementById("chat-container"),
});

kairo.init();

Con token de validación

import { createChatWidgetWithToken } from "kairo-agents";
import "kairo-agents/styles.css";

createChatWidgetWithToken(document.getElementById("chat-container"), {
  validateUrl: "https://tu-servidor.com/validate-token",
  token: "TOKEN_DEL_USUARIO",
  title: "Soporte",
});

Transporte HTTP — opciones

import { createHttpTransport } from "kairo-agents";

const transport = createHttpTransport({
  url: "https://tu-servidor.com/chat",

  // Cabeceras adicionales (ej. autenticación)
  headers: {
    Authorization: "Bearer TOKEN",
  },

  // Tiempo máximo de espera por respuesta (ms)
  timeout: 30_000,
});

Personalización visual

createChatWidget(container, {
  transport,
  colorScheme: "light",
  theme: {
    primaryColor: "#4F46E5",
    backgroundColor: "#ffffff",
    textColor: "#111827",
    borderRadius: "12px",
  },
  // Avatar del asistente
  assistantAvatarLetter: "K",
  // o imagen:
  // assistantAvatarUrl: "https://cdn.ejemplo.com/avatar.png",

  // Botón flotante personalizado
  launcherImageUrl: "https://cdn.ejemplo.com/logo.png",
  launcherMessage: "¿En qué te puedo ayudar?",
});

Menús guiados (SDK v2)

import { createChatWidget, createKairoApiTransport } from "kairo-agents";

const transport = createKairoApiTransport({
  baseUrl: "https://api.kairo.com",
  widgetToken: "TU_TOKEN",
});

createChatWidget(container, {
  transport,
  title: "Asistente",
});

API — exports principales

| Export | Tipo | Descripción | |--------|------|-------------| | createChatWidget | función | Monta el widget en un HTMLElement | | createHttpTransport | función | Transporte HTTP genérico | | createKairoApiTransport | función | Transporte oficial Kairo (init + nodos + chat) | | KairoChat | clase | Integración completa con la plataforma Kairo | | AgentsChat | clase | Cliente de chat de bajo nivel (sin UI) | | createChatWidgetWithToken | función | Widget con validación de token previa | | wrapTransportWithBootstrapCache | función | Precarga la respuesta inicial del asistente | | buildSdkV2Tree | función | Construye el árbol de menús desde nodos SDK v2 |

Tipos exportados

ChatWidgetOptions · ChatWidgetTheme · ChatWidgetColorScheme · ChatWidgetPlacement · ChatWidgetFaqItem · ChatWidgetProductItem · AgentsChatOptions · ChatTransport · ChatMessage · KairoChatOptions · KairoApiClientConfig

Requisitos

• Navegador moderno con soporte de ES2020 (Chrome 80+, Firefox 74+, Safari 13.1+, Edge 80+)
• Node.js 18+ para el entorno de build de tu proyecto