Ver toda la documentación

Stella AI Chatbot: Guía de Instalación y Manual de Usuario

Stella AI Chatbot para sitios web y atención al cliente

Guía de instalación de Stella AI Chatbot que cubre automatización FAQ, captura de leads, conversaciones IA, RAG, transferencia humana y analíticas Pro.

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

  1. Node.js 18+ - Entorno requerido para ejecutar el servidor backend del chatbot.
  2. npm - Requerido para instalar las dependencias del proyecto.
  3. Navegador moderno - Requerido para acceder al panel de administración y probar el comportamiento del widget.
  4. PostgreSQL 13+ (opcional en Pro) - Solo es necesario si eliges el modo de almacenamiento PostgreSQL.
  5. pgvector (opcional en Pro) - Requerido para búsqueda de similitud vectorial en PostgreSQL en modo RAG.
  6. Ollama (opcional en Pro) - Solo es necesario si deseas generación local de embeddings sin costo de API.

1.2 Descargar y preparar

  1. Extraer paquete - Descomprime stella-ai-chatbot-free o stella-ai-chatbot-pro.
  2. Abrir carpeta en terminal - Ejecuta todos los comandos de instalación/inicio desde este directorio.
  3. Instalar dependencias - Descarga todas las bibliotecas backend necesarias.
npm install

1.3 Configurar entorno

  1. Crear .env - Copia .env.example a .env.
  2. 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).
  3. 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

  1. Abrir instalador - /install inicializa el sistema del chatbot.
  2. Ingresar install token - Confirma instalación autorizada.
  3. Seleccionar modo de almacenamiento:
    • Free: almacenamiento JSON.
    • Pro: JSON o PostgreSQL.
  4. Completar instalación - Crea valores/ajustes predeterminados.
  5. Se genera install.lock - Evita reinstalación accidental y se guarda en la carpeta data.

1.6 Insertar widget en cualquier sitio web

  1. Abrir sección Embed Code - Genera script para integración frontend.
  2. Copiar script - Incluye cargador del widget y URL base de API.
  3. Pegar antes de </body> - Asegura que el widget cargue después del contenido.
  4. Actualizar sitio - Verifica que el chatbot aparezca y funcione.

1.7 Checklist de producción

  1. Habilitar HTTPS - Protege tráfico y credenciales.
  2. Usar secretos fuertes - Evita compromisos de token/sesión.
  3. Restringir dominios - Evita uso indebido de widget/API en sitios no autorizados.
  4. Proteger instalador - Bloquea ataques públicos de reinstalación.
  5. Habilitar controles CSRF/seguridad - Protege operaciones de escritura en admin.
  6. 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

  1. Abrir /admin - Accede a la página de entrada de administración.
  2. Iniciar sesión - Usa credenciales de .env.
  3. Navegar menú - Overview, Settings, FAQs, Logs.

2.2 Página Overview

  1. Estadísticas de uso - Muestra resumen de actividad del chatbot.
  2. Matched vs unmatched - Muestra tendencia de calidad de respuesta.
  3. Top matched keywords - Identifica consultas con respuesta exitosa.
  4. Top unmatched questions - Muestra huecos de contenido FAQ/AI para mejorar.

2.3 Página Settings

A. Core Identity

  1. Chatbot Name - Título visible en el encabezado del chat.
  2. Avatar Upload - Imagen de marca visible en launcher y chat.
  3. Avatar Shape - Controla si el avatar se ve redondo o cuadrado.
  4. Show Live Preview - Activa/desactiva vista previa en tiempo real en admin.

B. Messaging & Engagement

  1. Welcome Message - Mensaje mostrado al abrir el chat.
  2. No Match Message - Respuesta de fallback cuando no hay coincidencia.
  3. Fuzzy Match - Coincide palabras/preguntas similares aunque no sean exactas.
  4. Fuzzy Threshold - Define qué tan estricta es la coincidencia difusa.
  5. Lead Capture - Captura nombre/email antes o durante la conversación.
  6. Lead Capture Prompt - Mensaje mostrado al solicitar datos del visitante.

C. Widget Appearance

  1. Widget Position - Coloca el launcher a la izquierda o derecha.
  2. Widget Size - Controla el diámetro/huella visual del launcher.
  3. Brand/Theme Colors - Alinea el widget con tu identidad visual.
  4. Avatar Size - Controla tamaño del avatar dentro del chat.
  5. Animation - Añade efectos como pulse/shake/float.
  6. Chatbox Width/Height - Controla dimensiones del panel de conversación.

D. System & Performance

  1. Items Per Page - Tamaño de paginación en tablas de admin.
  2. Log Retention Days - Días de conservación de logs antes de limpiar.
  3. Auto Cleanup - Elimina automáticamente datos antiguos por regla de retención.
  4. Enforce HTTPS - Bloquea solicitudes no seguras sin HTTPS (no-localhost).
  5. Enforce Admin CSRF - Requiere token CSRF para escrituras en admin.

E. Categories

  1. Add Category - Crea nuevas agrupaciones para flujos FAQ/chat.
  2. Recommended Categories - Hasta 3 categorías destacadas al inicio del widget.
  3. Delete Category - Elimina categorías no usadas (o aplica lógica de merge/reasignación).

F. Embed Code

  1. API Base URL - Define backend URL usada por el script del widget.
  2. Allowed Widget Domains - Restringe dónde puede ejecutarse el widget.
  3. Widget Domain Policy - restricted obliga lista de dominios permitidos.
  4. Regenerate / Copy Code - Regenera y copia el script de inserción.

2.4 Funciones Pro en Settings (Pro)

A. Human Handoff (Pro)

  1. Enable Handoff - Activa escalamiento a soporte humano.
  2. Escalate After Unmatched - Número de fallos antes de escalar.
  3. Handoff Message - Mensaje mostrado cuando se activa el escalamiento.
  4. Support URL - Enlace para contactar soporte humano.
  5. Business Hours - Franja horaria opcional para comportamiento de handoff.

B. AI Powered Responses (Pro)

  1. AI Provider - Selecciona proveedor LLM backend.
  2. API Key - Clave de autenticación del proveedor.
  3. Load Models - Carga modelos disponibles para ese proveedor/clave.
  4. AI Model - Modelo usado para generar respuestas.
  5. Test Connection - Verifica configuración de proveedor/modelo/clave.
  6. Max Tokens - Longitud máxima de salida de respuesta AI.
  7. System Instructions - Define comportamiento, tono y reglas del bot.
  8. AI Disclaimer - Texto opcional de aviso bajo respuestas AI.

C. Vector Retrieval (RAG) (Pro)

  1. Enable RAG - Permite recuperar contenido indexado del sitio web.
  2. Use PostgreSQL pgvector - Habilita almacenamiento/búsqueda vectorial escalable.
  3. Embedding Provider - Servicio para convertir texto en vectores.
  4. Embedding API Key - Autenticación del proveedor de embeddings.
  5. Fetch Models - Carga modelos de embedding disponibles.
  6. Embedding Model - Modelo usado para indexación y consultas.
  7. Test Embedding Connection - Verifica endpoint de embeddings.
  8. Crawl Root URL / Sitemap - Define puntos de inicio de rastreo.
  9. Max Pages / Max Depth - Controla tamaño y profundidad del rastreo.
  10. Chunk Size / Overlap - Controla segmentación de texto para mejor retrieval.
  11. Include / Exclude Patterns - Control fino de URLs a rastrear.
  12. Resume Mode - Omite URLs ya indexadas en recrawl.
  13. Crawl Website Content - Inicia trabajo de indexación.
  14. RAG Ranking Mode - Controla estrategia de ranking (Balanced / Exact Product First).

2.5 Página FAQs

  1. Add FAQ - Creación manual de Q&A con keyword única.
  2. Edit/Delete FAQ - Mantiene y corrige respuestas existentes.
  3. Import File - Carga masiva desde TXT/CSV/CSB/DOCX.
  4. Delimiter Option - Interpreta formatos personalizados (:, ,, |, etc).
  5. Duplicate Keyword Handling - Omitir o agregar sufijo a duplicados.
  6. Category Handling - Crear categorías faltantes o usar categoría fallback.
  7. Import Summary - Muestra conteos de agregados/rechazados/duplicados.

2.6 Página Logs

  1. Session Filters - Buscar por clave de sesión, nombre o email.
  2. Show Chat - Abre historial solo de la sesión seleccionada.
  3. Leads Table - Muestra datos de contacto capturados.
  4. Pagination - Navega grandes volúmenes con controles arriba/abajo.

2.7 Comportamiento frontend

  1. Widget Open - El usuario abre launcher e inicia chat.
  2. Welcome/Categories - Se muestran introducción y categorías recomendadas (si está habilitado).
  3. User Query Handling:
    • Free: flujo FAQ + fuzzy match.
    • Pro: FAQ + AI + RAG + reglas de handoff.
  4. Lead Collection - Se muestra formulario nombre/email cuando está habilitado.
  5. Logging - Se guardan sesiones/mensajes/leads para analítica.

2.8 Troubleshooting

  1. Widget no visible - Valida embed code, política de dominio y consola del navegador.
  2. Respuestas AI cortas - Prueba otro modelo/proveedor, sube max tokens, revisa metadata del proveedor.
  3. RAG no responde - Confirma crawl, configuración de embeddings y modo de ranking.
  4. Instalación bloqueada - Verifica token de instalación y comportamiento lock/maintenance.

2.9 Ruta de despliegue recomendada

  1. Empieza con FAQ + categorías - Construye una base confiable de respuestas.
  2. Activa fuzzy match - Mejora tolerancia a variaciones en preguntas.
  3. Activa lead capture - Comienza a captar contactos calificados.
  4. (Pro) Activa AI - Gestiona consultas de lenguaje natural más amplias.
  5. (Pro) Activa RAG - Basa respuestas en contenido propio del sitio.
  6. (Pro) Activa handoff - Escala necesidades complejas a humanos.
  7. Finaliza seguridad + despliega - Bloquea políticas y publica en producción.