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ón

1.1 Requisitos

Node.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 preparar

Extraer 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 install

1.3 Configurar entorno

Crear .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ón

npm start

/install - Asistente de configuración inicial.
/admin - Inicio de sesión y panel de administración.

1.5 Pasos del instalador

Abrir 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 web

Abrir 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ón

Habilitar 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 admin

Abrir /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 Overview

Estadí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 Settings

A. Core Identity

Chatbot 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 & Engagement

Welcome 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 Appearance

Widget 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 & Performance

Items 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. Categories

Add 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 Code

API 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 FAQs

Add 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 Logs

Session 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 frontend

Widget 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 Troubleshooting

Widget 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 recomendada

Empieza 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.