FlowHunt JS API: Guida all'integrazione per utenti avanzati

Riferimento completo per l’integrazione della FlowHunt JS API v2. Scopri come incorporare il chatbot, iscriverti a tutti i 10 eventi, utilizzare le variabili di flusso, tracciare le interazioni con i parametri URL e controllare la finestra di chat in modo programmatico.

FlowHunt JavaScript API Chatbot Integration

La FlowHunt JS API ti offre il pieno controllo su come il tuo chatbot si integra con il tuo sito web. Utilizzando il codice di integrazione v2, puoi incorporare il chatbot, iscriverti agli eventi di ciclo di vita e interazione, passare dati dinamici tramite variabili di flusso, tracciare le interazioni con parametri URL e controllare la finestra di chat in modo programmatico.

Questa guida copre ogni aspetto della JS API con esempi di codice che puoi copiare e adattare al tuo progetto.

Codice di integrazione (v2)

Quando crei un chatbot in FlowHunt, ottieni uno snippet di integrazione. Copialo e incollalo nel tuo HTML subito prima del tag di chiusura </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>

Sostituisci YOUR_CHATBOT_ID e YOUR_WORKSPACE_ID con i valori dal tuo pannello di controllo FlowHunt. L’ID del chatbot nel nome della variabile globale (window.FHChatbot_YOUR_CHATBOT_ID) utilizza underscore al posto dei trattini.

Sovrascrivere la configurazione con setConfig()

Prima di chiamare init(), puoi sovrascrivere le impostazioni predefinite 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>

Opzioni di configurazione disponibili

OptionTypeDescrizione
headerTitlestringTesto personalizzato del titolo dell’intestazione
maxWindowWidthstringLarghezza massima della finestra di chat (ad esempio, '700px')
maxWindowHeightstringAltezza massima della finestra di chat
inputPlaceholderstringTesto segnaposto per il campo di inserimento dei messaggi
showChatButtonbooleanMostra o nascondi il pulsante di chat flottante predefinito
openChatPanelbooleanApri automaticamente il pannello di chat al caricamento della pagina
flowVariablesobjectCoppie chiave-valore di dati personalizzati passati al flusso
urlSuffixstringStringa di query aggiunta a tutti gli URL generati dal chatbot
cookieConsentbooleanAbilita la persistenza della sessione tramite cookie
embeddedstringAttiva la modalità incorporata (nessun pulsante di chiusura)
themestringModalità tema
Logo

Pronto a far crescere il tuo business?

Inizia oggi la tua prova gratuita e vedi i risultati in pochi giorni.

Richiedi demo Accedi

Variabili di flusso: Passare dati dinamici

Le variabili di flusso ti permettono di inviare dati personalizzati dal tuo sito web al flusso del chatbot. Questo consente conversazioni personalizzate basate sul contesto dell’utente.

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

Una volta impostate, queste variabili sono accessibili all’interno della logica del flusso del chatbot, permettendoti di personalizzare le risposte, instradare le conversazioni o passare il contesto agli agenti IA.

Suffisso URL: Tracciare le interazioni del chatbot

Il parametro urlSuffix aggiunge una stringa di query a ogni URL generato dal chatbot. Questo è utile per tracciare il traffico originato dal chatbot negli strumenti di analisi:

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

Casi d’uso:

  • Tracciare le conversioni dalle interazioni del chatbot in Google Analytics.
  • Analizzare il comportamento degli utenti dopo aver interagito con il chatbot.
  • Attribuire le campagne che stimolano l’engagement del chatbot.

Riferimento degli eventi

La FlowHunt JS API invia 10 eventi personalizzati sull’oggetto window. Tutti gli eventi utilizzano l’API CustomEvent con bubbles: true e composed: true.

onFHChatbotReady

Viene attivato quando il widget del chatbot è completamente renderizzato e pronto per l’uso.

  • Dati dell’evento: Nessuno
  • Quando: Dopo che il DOM del widget è montato e il pulsante di chat è visibile.

onFHChatbotSessionCreated

Viene attivato quando viene creata una nuova sessione di chat sul server. Si attiva anche quando la sessione viene riavviata.

  • Dati dell’evento: Nessuno
  • Quando: Dopo una chiamata API di creazione sessione riuscita.

onFHChatbotWindowOpened

Viene attivato quando l’utente apre la finestra di chat.

  • Dati dell’evento: Nessuno
  • Quando: Il pannello di chat diventa visibile.
  • Nota: Non viene attivato in modalità incorporata.

onFHChatbotWindowClosed

Viene attivato quando l’utente chiude la finestra di chat.

  • Dati dell’evento: Nessuno
  • Quando: Il pannello di chat viene nascosto.
  • Nota: Non viene attivato in modalità incorporata.

onFHMessageSent

Viene attivato quando l’utente invia un messaggio.

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

onFHMessageReceived

Viene attivato quando il chatbot riceve e visualizza una risposta.

  • Dati dell’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"
  }
}

Il campo sender è opzionale e presente solo quando è coinvolto un agente umano.

onFHFormDataSent

Viene attivato quando l’utente invia dati del modulo tramite il chatbot.

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

onFHFeedback

Viene attivato quando un utente dà un feedback positivo o negativo su un messaggio del chatbot.

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

Il valore di feedback è "P" per positivo (pollice in su) o "N" per negativo (pollice in giù).

onFHToolCall

Viene attivato quando uno strumento o un’azione viene eseguito durante l’elaborazione del flusso.

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

Nota: Viene attivato solo nelle modalità flowAssistant e flowAssistantV3, non nella modalità chatbot standard.

onFHError

Viene attivato quando si verifica un errore durante il funzionamento del chatbot.

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

Iscrizione agli eventi

Ci sono due modi per iscriversi agli eventi del chatbot.

Metodo 1: Listener di eventi Window

Usa window.addEventListener ovunque nella tua pagina. Questo funziona anche prima del caricamento del chatbot:

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

Per smettere di ascoltare un evento, usa removeEventListener con lo stesso riferimento alla funzione:

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

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

Metodo 2: Metodi di callback del gestore

All’interno del callback init(), usa i metodi integrati del gestore 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);
  });
});

Riferimento dei metodi del gestore

MethodParametersDescrizione
onSessionCreated(fn)fn: () => voidAscolta la creazione della sessione
onWindowOpened(fn)fn: () => voidAscolta l’apertura della finestra
onWindowClosed(fn)fn: () => voidAscolta la chiusura della finestra
onMessageSent(fn)fn: (event) => voidAscolta i messaggi dell’utente
onMessageReceived(fn)fn: (event) => voidAscolta le risposte del bot
onFormDataSent(fn)fn: (event) => voidAscolta gli invii di moduli
onFeedback(fn)fn: (event) => voidAscolta il feedback dell’utente
onToolCall(fn)fn: (event) => voidAscolta le esecuzioni degli strumenti
onError(fn)fn: (event) => voidAscolta gli errori
openChat()—Apre il pannello di chat
closeChat()—Chiude il pannello di chat

Attivazione personalizzata della chat: Nascondere il pulsante e aprire al clic

Per controllare completamente quando il chatbot appare, nascondi il pulsante flottante predefinito e apri la chat in modo programmatico — ad esempio, dal tuo pulsante personalizzato.

Esempio 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>

Mostrare un pulsante personalizzato solo quando il chatbot è pronto

Puoi combinare l’attivazione nascosta con i listener di eventi per creare interazioni avanzate:

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

Esempio di integrazione completo

Un esempio funzionante completo che dimostra le sovrascritture di configurazione, il tracciamento degli eventi e l’attivazione personalizzata della chat insieme:

<!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>

Domande frequenti

Quali eventi posso ascoltare con la FlowHunt JS API?

La FlowHunt JS API emette 10 eventi: onFHChatbotReady, onFHChatbotSessionCreated, onFHChatbotWindowOpened, onFHChatbotWindowClosed, onFHMessageSent, onFHMessageReceived, onFHFormDataSent, onFHFeedback, onFHToolCall e onFHError. Puoi iscriverti a questi usando window.addEventListener o tramite i metodi di callback del gestore del chatbot.

Come nascondo il pulsante di chat predefinito e apro il chatbot in modo programmatico?

Usa l'opzione di configurazione showChatButton: false per nascondere il pulsante predefinito, poi chiama chatbotManager.openChat() per aprire il chatbot secondo le tue condizioni — ad esempio, al clic su un pulsante personalizzato.

Qual è la differenza tra i metodi di callback del gestore e window.addEventListener?

Entrambi gli approcci funzionano. I metodi di callback del gestore (ad esempio, chatbotManager.onMessageSent(fn)) vengono chiamati all'interno del callback init e sono legati all'istanza del gestore. L'approccio window.addEventListener (ad esempio, window.addEventListener('onFHMessageSent', fn)) può essere configurato ovunque nella tua pagina, anche prima del caricamento del chatbot.

Come passo dati personalizzati al chatbot usando le variabili di flusso?

Usa l'opzione di configurazione flowVariables in setConfig() per passare coppie chiave-valore come ID utente, e-mail o URL della pagina. Queste variabili diventano disponibili nel flusso del chatbot per risposte personalizzate.

Quali dati sono disponibili nei gestori di eventi?

Gli eventi che contengono dati li includono in event.detail.metadata. Ad esempio, onFHMessageSent include il contenuto del messaggio e il timestamp, onFHMessageReceived include il flow_id, il message_id e il testo del messaggio, e onFHFeedback include il message_id e se il feedback è stato positivo o negativo.