Guía de instalación y usuario de Stella AI Chatbot

Esta guía cubre las ediciones Free y Pro en un solo lugar. Cuando una función es exclusiva de Pro, está marcada como (Pro).1. Instalación1.1 RequisitosNode.js 18+ - Entorno requerido para ejecutar el servidor backend del chatbot.npm - Requerido para instalar las dependencias del proyecto.Navegador moderno - Requerido para acceder al panel de administración y probar el comportamiento del widget.PostgreSQL 13+ (opcional en Pro) - Solo es necesario si eliges el modo de almacenamiento PostgreSQL.pgvector (opcional en Pro) - Requerido para búsqueda de similitud vectorial en PostgreSQL en modo RAG.Ollama (opcional en Pro) - Solo es necesario si deseas generación local de embeddings sin costo de API.1.2 Descargar y prepararExtraer paquete - Descomprime stella-ai-chatbot-free o stella-ai-chatbot-pro.Abrir carpeta en terminal - Ejecuta todos los comandos de instalación/inicio desde este directorio.Instalar dependencias - Descarga todas las bibliotecas backend necesarias.npm install1.3 Configurar entornoCrear .env - Copia .env.example a .env.Configurar variables obligatorias:NODE_ENV - Define el modo de ejecución (development o production).APP_SECRET - Se usa para firmar/verificar tokens y sesiones seguras.ADMIN_USER - Usuario de inicio de sesión admin.ADMIN_PASS - Contraseña de inicio de sesión admin.INSTALL_TOKEN - Protege el instalador contra accesos no autorizados.CORS_ORIGINS / ALLOWED_ORIGINS - Controla qué orígenes pueden llamar APIs.DATA_ENCRYPTION_KEY - Se usa para cifrar datos sensibles (si está soportado en tu edición).Variables opcionales:PORT - Puerto del servidor (la plataforma puede sobrescribirlo dinámicamente).TRUST_PROXY=true - Habilita detección correcta de IP detrás de reverse proxy/CDN.1.4 Iniciar aplicaciónnpm start/install - Asistente de configuración inicial./admin - Inicio de sesión y panel de administración.1.5 Pasos del instaladorAbrir instalador - /install inicializa el sistema del chatbot.Ingresar install token - Confirma instalación autorizada.Seleccionar modo de almacenamiento:Free: almacenamiento JSON.Pro: JSON o PostgreSQL.Completar instalación - Crea valores/ajustes predeterminados.Se genera install.lock - Evita reinstalación accidental y se guarda en la carpeta data.1.6 Insertar widget en cualquier sitio webAbrir sección Embed Code - Genera script para integración frontend.Copiar script - Incluye cargador del widget y URL base de API.Pegar antes de </body> - Asegura que el widget cargue después del contenido.Actualizar sitio - Verifica que el chatbot aparezca y funcione.1.7 Checklist de producciónHabilitar HTTPS - Protege tráfico y credenciales.Usar secretos fuertes - Evita compromisos de token/sesión.Restringir dominios - Evita uso indebido de widget/API en sitios no autorizados.Proteger instalador - Bloquea ataques públicos de reinstalación.Habilitar controles CSRF/seguridad - Protege operaciones de escritura en admin.Definir política de retención - Mantiene logs gestionables y conformes.2. Guía de usuario (Paso a paso)2.1 Inicio de sesión adminAbrir /admin - Accede a la página de entrada de administración.Iniciar sesión - Usa credenciales de .env.Navegar menú - Overview, Settings, FAQs, Logs.2.2 Página OverviewEstadísticas de uso - Muestra resumen de actividad del chatbot.Matched vs unmatched - Muestra tendencia de calidad de respuesta.Top matched keywords - Identifica consultas con respuesta exitosa.Top unmatched questions - Muestra huecos de contenido FAQ/AI para mejorar.2.3 Página SettingsA. Core IdentityChatbot Name - Título visible en el encabezado del chat.Avatar Upload - Imagen de marca visible en launcher y chat.Avatar Shape - Controla si el avatar se ve redondo o cuadrado.Show Live Preview - Activa/desactiva vista previa en tiempo real en admin.B. Messaging & EngagementWelcome Message - Mensaje mostrado al abrir el chat.No Match Message - Respuesta de fallback cuando no hay coincidencia.Fuzzy Match - Coincide palabras/preguntas similares aunque no sean exactas.Fuzzy Threshold - Define qué tan estricta es la coincidencia difusa.Lead Capture - Captura nombre/email antes o durante la conversación.Lead Capture Prompt - Mensaje mostrado al solicitar datos del visitante.C. Widget AppearanceWidget Position - Coloca el launcher a la izquierda o derecha.Widget Size - Controla el diámetro/huella visual del launcher.Brand/Theme Colors - Alinea el widget con tu identidad visual.Avatar Size - Controla tamaño del avatar dentro del chat.Animation - Añade efectos como pulse/shake/float.Chatbox Width/Height - Controla dimensiones del panel de conversación.D. System & PerformanceItems Per Page - Tamaño de paginación en tablas de admin.Log Retention Days - Días de conservación de logs antes de limpiar.Auto Cleanup - Elimina automáticamente datos antiguos por regla de retención.Enforce HTTPS - Bloquea solicitudes no seguras sin HTTPS (no-localhost).Enforce Admin CSRF - Requiere token CSRF para escrituras en admin.E. CategoriesAdd Category - Crea nuevas agrupaciones para flujos FAQ/chat.Recommended Categories - Hasta 3 categorías destacadas al inicio del widget.Delete Category - Elimina categorías no usadas (o aplica lógica de merge/reasignación).F. Embed CodeAPI Base URL - Define backend URL usada por el script del widget.Allowed Widget Domains - Restringe dónde puede ejecutarse el widget.Widget Domain Policy - restricted obliga lista de dominios permitidos.Regenerate / Copy Code - Regenera y copia el script de inserción.2.4 Funciones Pro en Settings (Pro)A. Human Handoff (Pro)Enable Handoff - Activa escalamiento a soporte humano.Escalate After Unmatched - Número de fallos antes de escalar.Handoff Message - Mensaje mostrado cuando se activa el escalamiento.Support URL - Enlace para contactar soporte humano.Business Hours - Franja horaria opcional para comportamiento de handoff.B. AI Powered Responses (Pro)AI Provider - Selecciona proveedor LLM backend.API Key - Clave de autenticación del proveedor.Load Models - Carga modelos disponibles para ese proveedor/clave.AI Model - Modelo usado para generar respuestas.Test Connection - Verifica configuración de proveedor/modelo/clave.Max Tokens - Longitud máxima de salida de respuesta AI.System Instructions - Define comportamiento, tono y reglas del bot.AI Disclaimer - Texto opcional de aviso bajo respuestas AI.C. Vector Retrieval (RAG) (Pro)Enable RAG - Permite recuperar contenido indexado del sitio web.Use PostgreSQL pgvector - Habilita almacenamiento/búsqueda vectorial escalable.Embedding Provider - Servicio para convertir texto en vectores.Embedding API Key - Autenticación del proveedor de embeddings.Fetch Models - Carga modelos de embedding disponibles.Embedding Model - Modelo usado para indexación y consultas.Test Embedding Connection - Verifica endpoint de embeddings.Crawl Root URL / Sitemap - Define puntos de inicio de rastreo.Max Pages / Max Depth - Controla tamaño y profundidad del rastreo.Chunk Size / Overlap - Controla segmentación de texto para mejor retrieval.Include / Exclude Patterns - Control fino de URLs a rastrear.Resume Mode - Omite URLs ya indexadas en recrawl.Crawl Website Content - Inicia trabajo de indexación.RAG Ranking Mode - Controla estrategia de ranking (Balanced / Exact Product First).2.5 Página FAQsAdd FAQ - Creación manual de Q&A con keyword única.Edit/Delete FAQ - Mantiene y corrige respuestas existentes.Import File - Carga masiva desde TXT/CSV/CSB/DOCX.Delimiter Option - Interpreta formatos personalizados (:, ,, |, etc).Duplicate Keyword Handling - Omitir o agregar sufijo a duplicados.Category Handling - Crear categorías faltantes o usar categoría fallback.Import Summary - Muestra conteos de agregados/rechazados/duplicados.2.6 Página LogsSession Filters - Buscar por clave de sesión, nombre o email.Show Chat - Abre historial solo de la sesión seleccionada.Leads Table - Muestra datos de contacto capturados.Pagination - Navega grandes volúmenes con controles arriba/abajo.2.7 Comportamiento frontendWidget Open - El usuario abre launcher e inicia chat.Welcome/Categories - Se muestran introducción y categorías recomendadas (si está habilitado).User Query Handling:Free: flujo FAQ + fuzzy match.Pro: FAQ + AI + RAG + reglas de handoff.Lead Collection - Se muestra formulario nombre/email cuando está habilitado.Logging - Se guardan sesiones/mensajes/leads para analítica.2.8 TroubleshootingWidget no visible - Valida embed code, política de dominio y consola del navegador.Respuestas AI cortas - Prueba otro modelo/proveedor, sube max tokens, revisa metadata del proveedor.RAG no responde - Confirma crawl, configuración de embeddings y modo de ranking.Instalación bloqueada - Verifica token de instalación y comportamiento lock/maintenance.2.9 Ruta de despliegue recomendadaEmpieza con FAQ + categorías - Construye una base confiable de respuestas.Activa fuzzy match - Mejora tolerancia a variaciones en preguntas.Activa lead capture - Comienza a captar contactos calificados.(Pro) Activa AI - Gestiona consultas de lenguaje natural más amplias.(Pro) Activa RAG - Basa respuestas en contenido propio del sitio.(Pro) Activa handoff - Escala necesidades complejas a humanos.Finaliza seguridad + despliega - Bloquea políticas y publica en producción.