FlowHunt JS API: Integratiegids voor Gevorderde Gebruikers

Volledige referentie voor de FlowHunt JS API v2-integratie. Leer hoe u de chatbot insluit, zich abonneert op alle 10 events, flow-variabelen gebruikt, interacties bijhoudt met URL-parameters en het chatvenster programmatisch bestuurt.

FlowHunt JavaScript API Chatbot Integration

De FlowHunt JS API geeft u volledige controle over hoe uw chatbot integreert met uw website. Met de v2-integratiecode kunt u de chatbot insluiten, zich abonneren op levenscyclus- en interactie-events, dynamische gegevens doorgeven via flow-variabelen, interacties bijhouden met URL-parameters en het chatvenster programmatisch besturen.

Deze gids behandelt elk aspect van de JS API met codevoorbeelden die u kunt kopiëren en aanpassen aan uw project.

Integratiecode (v2)

Wanneer u een chatbot aanmaakt in FlowHunt, ontvangt u een integratiefragment. Kopieer en plak het in uw HTML vlak voor de afsluitende </body>-tag:

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

Vervang YOUR_CHATBOT_ID en YOUR_WORKSPACE_ID door de waarden uit uw FlowHunt-dashboard. Het chatbot-ID in de globale variabelenaam (window.FHChatbot_YOUR_CHATBOT_ID) gebruikt underscores in plaats van koppeltekens.

Configuratie Overschrijven met setConfig()

Voordat u init() aanroept, kunt u de standaard chatbot-instellingen overschrijven met 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>

Beschikbare Configuratieopties

OptionTypeDescription
headerTitlestringAangepaste koptekst
maxWindowWidthstringMaximale breedte van het chatvenster (bijv. '700px')
maxWindowHeightstringMaximale hoogte van het chatvenster
inputPlaceholderstringPlaatsaanduidingstekst voor het berichtinvoerveld
showChatButtonbooleanDe standaard zwevende chatknop tonen of verbergen
openChatPanelbooleanHet chatpaneel automatisch openen bij het laden van de pagina
flowVariablesobjectSleutel-waardeparen van aangepaste gegevens die aan de flow worden doorgegeven
urlSuffixstringQuerystring die wordt toegevoegd aan alle door de chatbot gegenereerde URL’s
cookieConsentbooleanSessiepersistentie via cookies inschakelen
embeddedstringInstellen om de ingesloten modus in te schakelen (geen sluitknop)
themestringThemamodus
Logo

Klaar om uw bedrijf te laten groeien?

Start vandaag uw gratis proefperiode en zie binnen enkele dagen resultaten.

Demo aanvragen Inloggen

Flow-variabelen: Dynamische Gegevens Doorgeven

Flow-variabelen stellen u in staat om aangepaste gegevens van uw website naar de chatbot-flow te sturen. Dit maakt gepersonaliseerde gesprekken mogelijk op basis van de gebruikerscontext.

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

Eenmaal ingesteld zijn deze variabelen toegankelijk binnen de logica van uw chatbot-flow, waarmee u antwoorden kunt personaliseren, gesprekken kunt routeren of context kunt doorgeven aan AI-agents.

URL Suffix: Chatbot-interacties Bijhouden

De parameter urlSuffix voegt een querystring toe aan elke URL die door de chatbot wordt gegenereerd. Dit is handig om chatbot-afkomstig verkeer bij te houden in analysetools:

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

Gebruiksscenario’s:

  • Conversies bijhouden van chatbot-interacties in Google Analytics.
  • Gebruikersgedrag analyseren na interactie met de chatbot.
  • Campagnes toewijzen die chatbot-betrokkenheid stimuleren.

Event-referentie

De FlowHunt JS API verzendt 10 aangepaste events op het window-object. Alle events gebruiken de CustomEvent API met bubbles: true en composed: true.

onFHChatbotReady

Wordt geactiveerd wanneer de chatbot-widget volledig is weergegeven en klaar is voor gebruik.

  • Event-gegevens: Geen
  • Wanneer: Nadat het widget-DOM is gemount en de chatknop zichtbaar is.

onFHChatbotSessionCreated

Wordt geactiveerd wanneer een nieuwe chatsessie op de server wordt aangemaakt. Wordt ook geactiveerd wanneer de sessie wordt herstart.

  • Event-gegevens: Geen
  • Wanneer: Na een succesvolle API-aanroep voor het aanmaken van een sessie.

onFHChatbotWindowOpened

Wordt geactiveerd wanneer de gebruiker het chatvenster opent.

  • Event-gegevens: Geen
  • Wanneer: Het chatpaneel wordt zichtbaar.
  • Opmerking: Wordt niet geactiveerd in de ingesloten modus.

onFHChatbotWindowClosed

Wordt geactiveerd wanneer de gebruiker het chatvenster sluit.

  • Event-gegevens: Geen
  • Wanneer: Het chatpaneel wordt verborgen.
  • Opmerking: Wordt niet geactiveerd in de ingesloten modus.

onFHMessageSent

Wordt geactiveerd wanneer de gebruiker een bericht verzendt.

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

onFHMessageReceived

Wordt geactiveerd wanneer de chatbot een antwoord ontvangt en weergeeft.

  • Event-gegevens (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"
  }
}

Het veld sender is optioneel en alleen aanwezig wanneer een menselijke agent betrokken is.

onFHFormDataSent

Wordt geactiveerd wanneer de gebruiker formuliergegevens indient via de chatbot.

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

onFHFeedback

Wordt geactiveerd wanneer een gebruiker duim-omhoog of duim-omlaag feedback geeft op een chatbot-bericht.

  • Event-gegevens (event.detail.metadata):
{
  "message_id": "msg_456",
  "content": "Optional feedback text",
  "feedback": "P"
}

De waarde van feedback is "P" voor positief (duim omhoog) of "N" voor negatief (duim omlaag).

onFHToolCall

Wordt geactiveerd wanneer een tool of actie wordt uitgevoerd tijdens de verwerking van de flow.

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

Opmerking: Wordt alleen geactiveerd in de modi flowAssistant en flowAssistantV3, niet in de standaard chatbot-modus.

onFHError

Wordt geactiveerd wanneer er een fout optreedt tijdens de werking van de chatbot.

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

Abonneren op Events

Er zijn twee manieren om u te abonneren op chatbot-events.

Methode 1: Window Event Listeners

Gebruik window.addEventListener overal op uw pagina. Dit werkt zelfs voordat de chatbot is geladen:

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

Om te stoppen met luisteren naar een event, gebruik removeEventListener met dezelfde functieverwijzing:

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

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

Methode 2: Manager Callback-methoden

Binnen de init()-callback gebruikt u de ingebouwde methoden van de chatbot manager:

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);
  });
});

Referentie Manager-methoden

MethodParametersDescription
onSessionCreated(fn)fn: () => voidLuisteren naar sessie-aanmaak
onWindowOpened(fn)fn: () => voidLuisteren naar het openen van het venster
onWindowClosed(fn)fn: () => voidLuisteren naar het sluiten van het venster
onMessageSent(fn)fn: (event) => voidLuisteren naar gebruikersberichten
onMessageReceived(fn)fn: (event) => voidLuisteren naar bot-antwoorden
onFormDataSent(fn)fn: (event) => voidLuisteren naar formulierinzendingen
onFeedback(fn)fn: (event) => voidLuisteren naar gebruikersfeedback
onToolCall(fn)fn: (event) => voidLuisteren naar tool-uitvoeringen
onError(fn)fn: (event) => voidLuisteren naar fouten
openChat()—Opent het chatpaneel
closeChat()—Sluit het chatpaneel

Aangepaste Chat-activering: Knop Verbergen en Openen bij Klik

Om volledig te bepalen wanneer de chatbot verschijnt, verbergt u de standaard zwevende knop en opent u de chat programmatisch — bijvoorbeeld via uw eigen aangepaste knop.

Volledig Voorbeeld

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

Een Aangepaste Knop Alleen Tonen Wanneer de Chatbot Gereed Is

U kunt verborgen activering combineren met event listeners om geavanceerde interacties te creëren:

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

Volledig Integratievoorbeeld

Een volledig werkend voorbeeld dat configuratie-overschrijvingen, event-tracking en aangepaste chat-activering samen demonstreert:

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

Veelgestelde vragen

Naar welke events kan ik luisteren met de FlowHunt JS API?

De FlowHunt JS API zendt 10 events uit: onFHChatbotReady, onFHChatbotSessionCreated, onFHChatbotWindowOpened, onFHChatbotWindowClosed, onFHMessageSent, onFHMessageReceived, onFHFormDataSent, onFHFeedback, onFHToolCall en onFHError. U kunt zich hierop abonneren via window.addEventListener of via de callback-methoden van de chatbot manager.

Hoe verberg ik de standaard chatknop en open ik de chatbot programmatisch?

Gebruik de configuratieoptie showChatButton: false om de standaardknop te verbergen en roep vervolgens chatbotManager.openChat() aan om de chatbot op uw eigen voorwaarden te openen — bijvoorbeeld bij een klik op een aangepaste knop.

Wat is het verschil tussen de callback-methoden van de manager en window.addEventListener?

Beide benaderingen werken. De callback-methoden van de manager (bijv. chatbotManager.onMessageSent(fn)) worden aangeroepen binnen de init-callback en zijn gekoppeld aan de manager-instantie. De window.addEventListener-benadering (bijv. window.addEventListener('onFHMessageSent', fn)) kan overal op uw pagina worden ingesteld, zelfs voordat de chatbot is geladen.

Hoe geef ik aangepaste gegevens door aan de chatbot met flow-variabelen?

Gebruik de configuratieoptie flowVariables in setConfig() om sleutel-waardeparen door te geven zoals gebruikers-ID, e-mailadres of pagina-URL. Deze variabelen worden beschikbaar binnen uw chatbot-flow voor gepersonaliseerde antwoorden.

Welke gegevens zijn beschikbaar in event handlers?

Events die gegevens bevatten, bevatten deze in event.detail.metadata. Bijvoorbeeld, onFHMessageSent bevat de berichtinhoud en het tijdstempel, onFHMessageReceived bevat de flow_id, message_id en berichttekst, en onFHFeedback bevat de message_id en of de feedback positief of negatief was.