Saturn Studio – Chat Widget

El chat widget de Saturn Studio permite la integración del robot de Saturn en cualquier aplicación web. El widget es el encargado de ejecutar el robot de Saturn mediante la URL del chat, proporcionando conversaciones persistentes, entrada por voz y personalización completa.

Table of Contents

Obtener chatUrl

Para obtener el chatUrl de su robot, ingrese a Saturn Studio, navegue al módulo Chat y haga clic en Trigger Chat para obtener la URL.

1. Implementación Estándar

Configuración básica del widget con valores predeterminados. Ideal para comenzar rápidamente.

<!DOCTYPE html>
<html>
  <head>
    <title>Su Sitio Web</title>
  </head>
  <body>
    <main>
      <!-- Su contenido existente -->
    </main>

    <!-- Integración del Widget de Saturn Studio -->
    <script src="https://studio.rocketbot.com/chat-widget.js"></script>
    <script>
      new SaturnStudioChatWidget({
        chatUrl: "https://studio.rocketbot.com/chat/bcc41e580..."
      });
    </script>
  </body>
</html>

Parámetro	Descripción	Ejemplo
chatUrl	URL del chat. Requerido	`https://studio.rocketbot.com/chat/bcc41e580...`

2. Implementación Avanzada

Personalización completa con todas las opciones disponibles

<script src="https://studio.rocketbot.com/chat-widget.js"></script>
<script> 
  new SaturnStudioChatWidget({ 
    // Configuración requerida 
    chatUrl: "https://studio.rocketbot.com/chat/bcc41e580...", 
 
    // Personalización de apariencia 
    primaryColor: "#bd0018", 
    secondaryColor: "#253237", 
    backgroundColor: "#ffffff", 
    textColor: "#333333", 
    botMessageColor: "#f1f3f5", 
    userMessageColor: null, 
    subtitleColor: "rgba(255,255,255,0.8)", 
    borderRadius: "12px", 
 
    // Posicionamiento y tamaño 
    position: "bottom-right", 
    width: "380px", 
    height: "500px", 
 
    // Botón de alternancia 
    showToggleButton: true, 
    buttonSize: "60px", 
    buttonPosition: { 
      bottom: "20px", 
      right: "20px" 
    }, 
 
    // Configuración de comportamiento 
    openByDefault: false, 
    showTimestamps: true, 
    showUserIcon: true, 
    showBotIcon: true, 
    autoFocus: true, 
    responseTimeout: 180000, 
    pollInterval: 1500, 
    animationDuration: "0.3s", 
 
    // Estilos personalizados 
    customCSS: ` 
      .rocketbot-chat-widget { 
        border-radius: 16px; 
        box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1); 
      } 
    `, 
  }); 
</script>

Parámetro	Descripción	Ejemplo
chatUrl	URL del chat. Requerido	`https://studio.rocketbot.com/chat/bcc41e580...`
primaryColor	Color principal de marca	#bd0018
secondaryColor	Color de acento secundario	#253237
backgroundColor	Color de fondo del chat	#ffffff
textColor	Color del texto	#333333
botMessageColor	Color de fondo de mensajes del bot	#f1f3f5
userMessageColor	Color de fondo de mensajes del usuario (null usa gradiente)	null
subtitleColor	Color del subtítulo	rgba(255,255,255,0.8)
borderRadius	Radio del borde del widget	12px
position	Posición del widget (bottom-right, bottom-left, top-right, top-left)	bottom-right
width	Ancho de la ventana de chat	380px
height	Altura de la ventana de chat	500px
showToggleButton	Mostrar botón de alternancia flotante	true
buttonSize	Tamaño del botón de alternancia	60px
buttonPosition	Posición del botón de alternancia	{bottom: “20px”, right: “20px”}
openByDefault	Abrir automáticamente al cargar la página	false
showTimestamps	Mostrar marcas de tiempo de mensajes	true
showUserIcon	Mostrar icono de usuario en mensajes	true
showBotIcon	Mostrar icono de bot en mensajes	true
autoFocus	Enfocar automáticamente la entrada al abrir	true
responseTimeout	Tiempo de espera máxima de respuesta del bot (ms)	180000
pollInterval	Intervalo de sondeo de mensajes (ms)	1500
animationDuration	Duración de las animaciones	0.3s
customCSS	CSS personalizado para el widget	.rocketbot-chat-widget { … }

Referencia de configuración

Métodos del Widget

Controle el widget programáticamente después de la inicialización:

const widget = new SaturnStudioChatWidget({ 
  chatUrl: "https://studio.rocketbot.com/chat/bcc41e580..."
}); 
 
// Métodos de control 
widget.toggleChat();              // Abrir/cerrar chat 
widget.startNewConversation();    // Limpiar e iniciar nueva conversación 
widget.destroy();                 // Eliminar widget completamente 
 
// Acceso al estado
console.log(widget.isOpen);           // boolean
console.log(widget.conversationId);   // string - ID de conversación persistente
console.log(widget.currentChatId);    // string - ID del chat activo
console.log(widget.config.robotId);   // string - ID del robot
console.log(widget.config.apiBaseUrl);// string - URL base

Características

Entrada por Voz

El widget incluye reconocimiento de voz automático que se activa cuando el navegador del usuario lo admite.

Cómo funciona:

Detecta automáticamente el soporte de la API de voz del navegador
El botón de micrófono aparece automáticamente cuando está disponible
Soporta grabación continua (mantener presionado para grabar)
La transcripción en tiempo real aparece en el campo de entrada
Icono cambia a “stop” mientras graba

Compatibilidad:

✅ Chrome/Edge: Soporte completo
⚠️ Safari: Limitado (funciona mejor en iOS)
❌ Firefox: No compatible

Conversaciones Persistentes

Las conversaciones persisten automáticamente a través de:

Actualizaciones y navegación de página
Reinicios del navegador (almacenado en sessionStorage y cookies)
Múltiples pestañas del mismo dominio

Iniciar nueva conversación: Use el botón + en el encabezado del chat para iniciar una conversación nueva y limpiar el historial.

Solución de problemas

El widget no aparece

Verifique que su robot de Saturn Studio esté ACTIVO y en ejecución
Verifique que la chatUrl sea correcta y tenga el formato “https://studio.rocketbot.com/chat/bcc41e580…”
Revise la consola del navegador en busca de errores
Confirme que el servidor esté ejecutándose y sea accesible
Asegúrese de que el primer módulo en su flujo sea un “Chat Trigger”
Asegúrese de que el último módulo en su flujo sea un “Send Message”

Error: “chatUrl is required”

El parámetro chatUrl es obligatorio
Asegúrese de incluirlo en la configuración: { chatUrl: “https://…” }

Error: “Invalid chatUrl format”

La URL debe seguir el formato: “https://studio.rocketbot.com/chat/bcc41e580…”
Verifique que la URL comience con https://
Verifique que el path contenga /chat/ seguido del ID del robot

Los mensajes no llegan

Asegúrese de que su robot de Saturn Studio esté ACTIVO
Verifique que su flujo comience con “Chat Trigger” y termine con “Send Message”
Revise la consola del navegador para ver errores de API

El historial no se carga

El widget busca conversaciones existentes usando el conversationId almacenado
Limpie sessionStorage y cookies si necesita empezar de cero
Use el botón + para iniciar una nueva conversación

Problemas de estilo

Use !important en customCSS si necesita sobrescribir estilos
Revise conflictos con CSS existente en su sitio
Use el inspector del navegador para depuración

Problemas de rendimiento

Aumente pollInterval para reducir solicitudes al servidor (predeterminado: 1500ms)
Ajuste responseTimeout según las necesidades de su robot (predeterminado: 180000ms)
Monitoree el rendimiento del servidor y del robot de Saturn

El reconocimiento de voz no funciona

Verifique que esté usando un navegador compatible (Chrome o Edge recomendados)
El sitio debe servirse por HTTPS para que funcione el reconocimiento de voz
Verifique los permisos del navegador para acceder al micrófono

Requisitos

Contar con un robot de Saturn Studio activo y en ejecución
Configuración de flujo con “Chat Trigger” como primer módulo
Configuración de flujo con “Send Message” como módulo final
URL del webhook del robot (formato: “https://studio.rocketbot.com/chat/bcc41e580…”)
HTTPS habilitado en el sitio web (recomendado, especialmente para reconocimiento de voz)