Widget JavaScript
Guía completa de integración y personalización del widget
Instalación Rápida
Integra el widget en tu sitio web en menos de 2 minutos:
Paso 1: Obtén tu Client ID
Accede a tu panel de administración y copia tu Client ID desde la sección de configuración del widget.
Paso 2: Incluye el Script
Agrega el siguiente código antes del cierre de la etiqueta </body> en tu HTML:
<!-- Assistant Virtual IA Widget -->
<script src="https://tu-dominio.com/widgets/assistant-widget.js?clientId=TU_CLIENT_ID"></script>
<!-- End Widget -->
Configuración
Puedes personalizar el widget desde el panel de administración o mediante la API. Las siguientes opciones están disponibles:
| Parámetro | Tipo | Valores | Descripción |
|---|---|---|---|
primaryColor |
string | Hex color (ej: #667eea) | Color principal del widget |
secondaryColor |
string | Hex color (ej: #764ba2) | Color secundario del widget |
position |
string | bottom-right, bottom-left, top-right, top-left | Posición del botón del widget en la pantalla |
welcomeMessage |
string | Cualquier texto | Mensaje de bienvenida cuando se abre el widget |
autoOpen |
boolean | true, false | Abrir automáticamente el widget al cargar la página |
theme |
string | light, dark, auto | Tema visual del widget |
showAvatar |
boolean | true, false | Mostrar avatar del asistente |
streamingEnabled |
boolean | true, false | Habilitar streaming de respuestas en tiempo real |
Características
-
Streaming en Tiempo Real
Las respuestas se muestran de forma incremental mientras se generan, mejorando la experiencia del usuario.
-
Comandos Personalizados
Crea comandos personalizados para acceder rápidamente a bases de conocimiento específicas.
-
Historial de Conversaciones
El widget mantiene un historial de conversaciones por sesión para referencia del usuario.
-
Diseño Responsive
Se adapta perfectamente a dispositivos móviles, tablets y escritorio.
-
Personalización Completa
Personaliza colores, posición, mensajes y comportamiento según tu marca.
-
Múltiples Bases de Conocimiento
Soporta múltiples bases de conocimiento y permite cambiar entre ellas dinámicamente.
Comandos Personalizados
Los comandos personalizados permiten a los usuarios acceder rápidamente a funcionalidades específicas o bases de conocimiento.
Formato de Comandos
Los comandos se definen con el prefijo /asistente seguido del nombre del comando:
/asistente [nombre-comando] [consulta]
Ejemplos de Comandos
/asistente help- Muestra la ayuda y comandos disponibles/asistente buscar ¿qué es el FUT?- Busca en la base de conocimiento/asistente siicontabilidad consulta sobre facturación- Usa un comando personalizado
Configurar Comandos Personalizados
Puedes configurar comandos personalizados desde el panel de administración:
{
"siicontabilidad": {
"description": "Consultas relacionadas con el SII de Chile",
"examples": [
"/asistente siicontabilidad ¿qué es el FUT?",
"/asistente siicontabilidad cómo declarar IVA"
],
"knowledgeBase": "sii_chile"
},
"legal": {
"description": "Consultas legales",
"examples": [
"/asistente legal contrato de trabajo",
"/asistente legal derechos del consumidor"
],
"knowledgeBase": "legal_chile"
}
}
API JavaScript
El widget expone una API JavaScript para control programático:
Inicialización Manual
// Inicializar el widget manualmente
window.initAssistantWidget('TU_CLIENT_ID', {
position: 'bottom-right',
autoOpen: false,
theme: 'light',
primaryColor: '#667eea',
secondaryColor: '#764ba2',
welcomeMessage: '¡Hola! ¿En qué puedo ayudarte?',
showAvatar: true,
streamingEnabled: true
});
Métodos Disponibles
open()
Abre el widget programáticamente:
// Obtener instancia del widget
const widget = window.AssistantWidget.getInstance('TU_CLIENT_ID');
// Abrir el widget
widget.open();
close()
Cierra el widget:
widget.close();
sendMessage(message)
Envía un mensaje programáticamente:
widget.sendMessage('¿Cuáles son los horarios de atención?');
setKnowledgeBase(kbId)
Cambia la base de conocimiento activa:
widget.setKnowledgeBase('kb-123-456');
Eventos
El widget emite eventos que puedes escuchar para integrar con tu aplicación:
onOpen
window.addEventListener('assistant-widget:open', (event) => {
console.log('Widget abierto');
// Tu código aquí
});
onClose
window.addEventListener('assistant-widget:close', (event) => {
console.log('Widget cerrado');
// Tu código aquí
});
onMessage
window.addEventListener('assistant-widget:message', (event) => {
console.log('Mensaje enviado:', event.detail.message);
// Tu código aquí
});
onResponse
window.addEventListener('assistant-widget:response', (event) => {
console.log('Respuesta recibida:', event.detail.response);
// Tu código aquí
});
Ejemplos de Uso
Ejemplo 1: Integración Básica
<!DOCTYPE html>
<html>
<head>
<title>Mi Sitio Web</title>
</head>
<body>
<h1>Bienvenido a mi sitio</h1>
<!-- Tu contenido aquí -->
<!-- Widget -->
<script src="https://tu-dominio.com/widgets/assistant-widget.js?clientId=TU_CLIENT_ID"></script>
</body>
</html>
Ejemplo 2: Con Configuración Personalizada
<script>
window.addEventListener('DOMContentLoaded', function() {
window.initAssistantWidget('TU_CLIENT_ID', {
position: 'bottom-left',
primaryColor: '#ff6b6b',
welcomeMessage: '¡Bienvenido! Estoy aquí para ayudarte.',
autoOpen: false
});
});
</script>
Ejemplo 3: Integración con React
import { useEffect } from 'react';
function App() {
useEffect(() => {
// Cargar script del widget
const script = document.createElement('script');
script.src = 'https://tu-dominio.com/widgets/assistant-widget.js?clientId=TU_CLIENT_ID';
script.async = true;
document.body.appendChild(script);
return () => {
// Limpiar al desmontar
document.body.removeChild(script);
};
}, []);
return <div>Mi Aplicación</div>;
}
Solución de Problemas
El widget no aparece
- Verifica que el script esté incluido antes de
</body> - Confirma que el Client ID sea correcto
- Revisa la consola del navegador para errores
El widget no responde
- Verifica que la API Key esté configurada correctamente
- Confirma que el cliente tenga cuota disponible
- Revisa que la base de conocimiento esté activa