FlowHunt JS API: Guía de integración para usuarios avanzados

Referencia completa para la integración de FlowHunt JS API v2. Aprenda a incrustar el chatbot, suscribirse a los 10 eventos, usar variables de flujo, rastrear interacciones con parámetros URL y controlar la ventana de chat programáticamente.

FlowHunt JavaScript API Chatbot Integration

La FlowHunt JS API te da control total sobre cómo tu chatbot se integra con tu sitio web. Usando el código de integración v2, puedes incrustar el chatbot, suscribirte a eventos de ciclo de vida e interacción, pasar datos dinámicos mediante variables de flujo, rastrear interacciones con parámetros URL y controlar la ventana de chat programáticamente.

Esta guía cubre todos los aspectos de la JS API con ejemplos de código que puedes copiar y adaptar a tu proyecto.

Código de integración (v2)

Cuando creas un chatbot en FlowHunt, obtienes un fragmento de integración. Cópialo y pégalo en tu HTML justo antes de la etiqueta de cierre </body>:

<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // The chatbot is ready — use chatbotManager here
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

Reemplaza YOUR_CHATBOT_ID y YOUR_WORKSPACE_ID con los valores de tu panel de FlowHunt. El ID del chatbot en el nombre de la variable global (window.FHChatbot_YOUR_CHATBOT_ID) usa guiones bajos en lugar de guiones.

Sobrescribir la configuración con setConfig()

Antes de llamar a init(), puedes sobrescribir la configuración predeterminada del chatbot usando setConfig():

<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      headerTitle: 'Support Assistant',
      maxWindowWidth: '700px',
      showChatButton: false,
      flowVariables: {
        userId: '12345',
        plan: 'enterprise'
      },
      urlSuffix: '?utm_source=chatbot'
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // Chatbot initialized with custom config
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

Opciones de configuración disponibles

OptionTypeDescripción
headerTitlestringTexto personalizado del título del encabezado
maxWindowWidthstringAncho máximo de la ventana de chat (por ejemplo, '700px')
maxWindowHeightstringAltura máxima de la ventana de chat
inputPlaceholderstringTexto del marcador de posición para el campo de entrada de mensajes
showChatButtonbooleanMostrar u ocultar el botón flotante de chat predeterminado
openChatPanelbooleanAbrir automáticamente el panel de chat al cargar la página
flowVariablesobjectPares clave-valor de datos personalizados pasados al flujo
urlSuffixstringCadena de consulta añadida a todas las URLs generadas por el chatbot
cookieConsentbooleanHabilitar la persistencia de sesión mediante cookies
embeddedstringActivar el modo incrustado (sin botón de cierre)
themestringModo de tema
Logo

¿Listo para hacer crecer tu negocio?

Comienza tu prueba gratuita hoy y ve resultados en días.

Solicitar demo Iniciar sesión

Variables de flujo: Pasar datos dinámicos

Las variables de flujo te permiten enviar datos personalizados desde tu sitio web al flujo del chatbot. Esto permite conversaciones personalizadas basadas en el contexto del usuario.

window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
  flowVariables: {
    userId: getCurrentUserId(),
    userEmail: getCurrentUserEmail(),
    currentPage: window.location.pathname,
    plan: 'enterprise'
  }
});

Una vez establecidas, estas variables son accesibles dentro de la lógica del flujo de tu chatbot, permitiéndote personalizar respuestas, enrutar conversaciones o pasar contexto a agentes de IA.

Sufijo URL: Rastrear interacciones del chatbot

El parámetro urlSuffix añade una cadena de consulta a cada URL generada por el chatbot. Esto es útil para rastrear el tráfico originado por el chatbot en herramientas de análisis:

window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
  urlSuffix: '?utm_source=chatbot&utm_medium=widget'
});

Casos de uso:

  • Rastrear conversiones de las interacciones del chatbot en Google Analytics.
  • Analizar el comportamiento del usuario después de interactuar con el chatbot.
  • Atribuir campañas que impulsan el engagement del chatbot.

Referencia de eventos

La FlowHunt JS API despacha 10 eventos personalizados en el objeto window. Todos los eventos usan la API CustomEvent con bubbles: true y composed: true.

onFHChatbotReady

Se dispara cuando el widget del chatbot se ha renderizado completamente y está listo para usar.

  • Datos del evento: Ninguno
  • Cuándo: Después de que el DOM del widget está montado y el botón de chat es visible.

onFHChatbotSessionCreated

Se dispara cuando se crea una nueva sesión de chat en el servidor. También se dispara cuando se reinicia la sesión.

  • Datos del evento: Ninguno
  • Cuándo: Después de una llamada API exitosa de creación de sesión.

onFHChatbotWindowOpened

Se dispara cuando el usuario abre la ventana de chat.

  • Datos del evento: Ninguno
  • Cuándo: El panel de chat se vuelve visible.
  • Nota: No se dispara en modo incrustado.

onFHChatbotWindowClosed

Se dispara cuando el usuario cierra la ventana de chat.

  • Datos del evento: Ninguno
  • Cuándo: El panel de chat se oculta.
  • Nota: No se dispara en modo incrustado.

onFHMessageSent

Se dispara cuando el usuario envía un mensaje.

  • Datos del evento (event.detail.metadata):
{
  "content": "Hello, I need help with...",
  "createdAt": "2026-02-19T10:30:00.000Z"
}

onFHMessageReceived

Se dispara cuando el chatbot recibe y muestra una respuesta.

  • Datos del evento (event.detail.metadata):
{
  "flow_id": "abc123",
  "message_id": "msg_456",
  "message": "Sure, I can help you with that!",
  "sender": {
    "sender_name": "Support Agent",
    "sender_avatar": "https://example.com/avatar.png"
  }
}

El campo sender es opcional y solo está presente cuando un agente humano está involucrado.

onFHFormDataSent

Se dispara cuando el usuario envía datos de formulario a través del chatbot.

  • Datos del evento (event.detail.metadata):
{
  "objectData": { "name": "John", "email": "john@example.com" },
  "createdAt": "2026-02-19T10:31:00.000Z"
}

onFHFeedback

Se dispara cuando un usuario da una valoración de pulgar arriba o pulgar abajo a un mensaje del chatbot.

  • Datos del evento (event.detail.metadata):
{
  "message_id": "msg_456",
  "content": "Optional feedback text",
  "feedback": "P"
}

El valor de feedback es "P" para positivo (pulgar arriba) o "N" para negativo (pulgar abajo).

onFHToolCall

Se dispara cuando se ejecuta una herramienta o acción durante el procesamiento del flujo.

  • Datos del evento (event.detail.metadata):
{
  "metadata": {
    "flow_id": "abc123",
    "message_id": "msg_789",
    "message": "Calling search API..."
  },
  "createdAt": "2026-02-19T10:32:00.000Z"
}

Nota: Solo se dispara en los modos flowAssistant y flowAssistantV3, no en el modo de chatbot estándar.

onFHError

Se dispara cuando ocurre un error durante la operación del chatbot.

  • Datos del evento (event.detail.metadata):
{
  "metadata": {
    "flow_id": "abc123",
    "message_id": "msg_err",
    "message": "Flow execution failed"
  },
  "createdAt": "2026-02-19T10:33:00.000Z"
}

Suscripción a eventos

Hay dos formas de suscribirse a los eventos del chatbot.

Método 1: Listeners de eventos de Window

Usa window.addEventListener en cualquier parte de tu página. Esto funciona incluso antes de que el chatbot se haya cargado:

<script>
document.addEventListener('DOMContentLoaded', function() {
  // Chatbot lifecycle events
  window.addEventListener('onFHChatbotReady', function(event) {
    console.log('Chatbot is ready');
  });

  window.addEventListener('onFHChatbotSessionCreated', function(event) {
    console.log('Session created');
  });

  window.addEventListener('onFHChatbotWindowOpened', function(event) {
    console.log('Chat window opened');
  });

  window.addEventListener('onFHChatbotWindowClosed', function(event) {
    console.log('Chat window closed');
  });

  // Message events
  window.addEventListener('onFHMessageSent', function(event) {
    console.log('User sent:', event.detail.metadata.content);
  });

  window.addEventListener('onFHMessageReceived', function(event) {
    console.log('Bot replied:', event.detail.metadata.message);
  });

  window.addEventListener('onFHFormDataSent', function(event) {
    console.log('Form submitted:', event.detail.metadata.objectData);
  });

  // Feedback
  window.addEventListener('onFHFeedback', function(event) {
    var feedback = event.detail.metadata;
    console.log('Feedback on message', feedback.message_id, ':',
      feedback.feedback);
  });

  // Tool calls (flowAssistant modes only)
  window.addEventListener('onFHToolCall', function(event) {
    console.log('Tool called:', event.detail.metadata);
  });

  // Errors
  window.addEventListener('onFHError', function(event) {
    console.error('Chatbot error:', event.detail.metadata);
  });
});
</script>

Para dejar de escuchar un evento, usa removeEventListener con la misma referencia de función:

var handleMessage = function(event) {
  console.log(event.detail.metadata);
};
window.addEventListener('onFHMessageReceived', handleMessage);

// Later, when you want to stop listening:
window.removeEventListener('onFHMessageReceived', handleMessage);

Método 2: Métodos de callback del administrador

Dentro del callback de init(), usa los métodos integrados del administrador del chatbot:

window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
  chatbotManager.onSessionCreated(function() {
    console.log('Session created');
  });

  chatbotManager.onWindowOpened(function() {
    console.log('Window opened');
  });

  chatbotManager.onWindowClosed(function() {
    console.log('Window closed');
  });

  chatbotManager.onMessageSent(function(event) {
    console.log('User sent:', event.metadata);
  });

  chatbotManager.onMessageReceived(function(event) {
    console.log('Bot replied:', event.metadata);
  });

  chatbotManager.onFormDataSent(function(event) {
    console.log('Form data:', event.metadata);
  });

  chatbotManager.onFeedback(function(event) {
    console.log('Feedback:', event.metadata);
  });

  chatbotManager.onToolCall(function(event) {
    console.log('Tool call:', event.metadata);
  });

  chatbotManager.onError(function(event) {
    console.error('Error:', event.metadata);
  });
});

Referencia de métodos del administrador

MethodParametersDescripción
onSessionCreated(fn)fn: () => voidEscuchar la creación de sesión
onWindowOpened(fn)fn: () => voidEscuchar la apertura de ventana
onWindowClosed(fn)fn: () => voidEscuchar el cierre de ventana
onMessageSent(fn)fn: (event) => voidEscuchar mensajes del usuario
onMessageReceived(fn)fn: (event) => voidEscuchar respuestas del bot
onFormDataSent(fn)fn: (event) => voidEscuchar envíos de formularios
onFeedback(fn)fn: (event) => voidEscuchar feedback del usuario
onToolCall(fn)fn: (event) => voidEscuchar ejecuciones de herramientas
onError(fn)fn: (event) => voidEscuchar errores
openChat()—Abre el panel de chat
closeChat()—Cierra el panel de chat

Activación personalizada del chat: Ocultar botón y abrir al hacer clic

Para controlar completamente cuándo aparece el chatbot, oculta el botón flotante predeterminado y abre el chat programáticamente — por ejemplo, desde tu propio botón personalizado.

Ejemplo completo

<!-- Your custom chat button -->
<button id="my-chat-button">Chat with us</button>

<!-- FlowHunt integration with hidden default button -->
<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      showChatButton: false
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // Open chat when your custom button is clicked
      document.getElementById('my-chat-button')
        .addEventListener('click', function() {
          chatbotManager.openChat();
        });
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

Mostrar un botón personalizado solo cuando el chatbot esté listo

Puedes combinar la activación oculta con listeners de eventos para crear interacciones avanzadas:

<button id="open-chat" style="display:none;">Need help?</button>

<script>
// Show a custom button only when the chatbot is ready
window.addEventListener('onFHChatbotReady', function() {
  document.getElementById('open-chat').style.display = 'block';
});
</script>

<!-- FlowHunt integration -->
<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      showChatButton: false
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      document.getElementById('open-chat')
        .addEventListener('click', function() {
          chatbotManager.openChat();
        });
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

Ejemplo de integración completo

Un ejemplo funcional completo que demuestra las sobrescrituras de configuración, el seguimiento de eventos y la activación personalizada del chat juntos:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>FlowHunt Chatbot Integration</title>
</head>
<body>
  <h1>My Website</h1>
  <button id="open-chat-btn">Talk to our AI assistant</button>
  <button id="close-chat-btn">Close chat</button>

  <!-- Subscribe to events before the chatbot loads -->
  <script>
  document.addEventListener('DOMContentLoaded', function() {
    window.addEventListener('onFHChatbotReady', function() {
      console.log('Chatbot widget is ready');
    });

    window.addEventListener('onFHChatbotSessionCreated', function() {
      console.log('New chat session started');
    });

    window.addEventListener('onFHMessageSent', function(event) {
      console.log('User message:', event.detail.metadata.content);
    });

    window.addEventListener('onFHMessageReceived', function(event) {
      console.log('Bot response:', event.detail.metadata.message);
    });

    window.addEventListener('onFHFeedback', function(event) {
      var fb = event.detail.metadata;
      if (fb.feedback === 'P') {
        console.log('Positive feedback on message', fb.message_id);
      } else {
        console.log('Negative feedback on message', fb.message_id);
      }
    });

    window.addEventListener('onFHError', function(event) {
      console.error('Chatbot error:', event.detail.metadata);
    });
  });
  </script>

  <!-- FlowHunt integration -->
  <script id="fh-chatbot-script-YOUR_CHATBOT_ID">
    var currentScript = document.currentScript
      || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

    var script = document.createElement('script');
    script.async = true;
    script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
      + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

    script.onload = function() {
      window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
        showChatButton: false,
        headerTitle: 'AI Assistant',
        maxWindowWidth: '600px',
        flowVariables: {
          source: 'website',
          page: window.location.pathname
        },
        urlSuffix: '?utm_source=chatbot'
      });

      window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
        document.getElementById('open-chat-btn')
          .addEventListener('click', function() {
            chatbotManager.openChat();
          });

        document.getElementById('close-chat-btn')
          .addEventListener('click', function() {
            chatbotManager.closeChat();
          });
      });
    };

    if (currentScript && currentScript.parentNode) {
      currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
    } else {
      document.head.appendChild(script);
    }
  </script>
</body>
</html>

Preguntas frecuentes

¿Qué eventos puedo escuchar con la FlowHunt JS API?

La FlowHunt JS API emite 10 eventos: onFHChatbotReady, onFHChatbotSessionCreated, onFHChatbotWindowOpened, onFHChatbotWindowClosed, onFHMessageSent, onFHMessageReceived, onFHFormDataSent, onFHFeedback, onFHToolCall y onFHError. Puedes suscribirte a ellos usando window.addEventListener o mediante los métodos de callback del administrador del chatbot.

¿Cómo oculto el botón de chat predeterminado y abro el chatbot programáticamente?

Usa la opción de configuración showChatButton: false para ocultar el botón predeterminado, y luego llama a chatbotManager.openChat() para abrir el chatbot según tus propias condiciones — por ejemplo, al hacer clic en un botón personalizado.

¿Cuál es la diferencia entre los métodos de callback del administrador y window.addEventListener?

Ambos enfoques funcionan. Los métodos de callback del administrador (por ejemplo, chatbotManager.onMessageSent(fn)) se llaman dentro del callback de init y están vinculados a la instancia del administrador. El enfoque de window.addEventListener (por ejemplo, window.addEventListener('onFHMessageSent', fn)) se puede configurar en cualquier parte de tu página, incluso antes de que se cargue el chatbot.

¿Cómo paso datos personalizados al chatbot usando variables de flujo?

Usa la opción de configuración flowVariables en setConfig() para pasar pares clave-valor como ID de usuario, correo electrónico o URL de página. Estas variables estarán disponibles dentro del flujo de tu chatbot para respuestas personalizadas.

¿Qué datos están disponibles en los manejadores de eventos?

Los eventos que contienen datos los incluyen en event.detail.metadata. Por ejemplo, onFHMessageSent incluye el contenido del mensaje y la marca de tiempo, onFHMessageReceived incluye el flow_id, message_id y el texto del mensaje, y onFHFeedback incluye el message_id y si el feedback fue positivo o negativo.