FlowHunt JS API: Integrationsleitfaden für fortgeschrittene Benutzer

Vollständige Referenz für die FlowHunt JS API v2-Integration. Erfahren Sie, wie Sie den Chatbot einbetten, alle 10 Events abonnieren, Flow-Variablen verwenden, Interaktionen mit URL-Parametern verfolgen und das Chat-Fenster programmatisch steuern.

FlowHunt JavaScript API Chatbot Integration

Die FlowHunt JS API gibt Ihnen die volle Kontrolle darüber, wie sich Ihr Chatbot in Ihre Website integriert. Mit dem v2-Integrationscode können Sie den Chatbot einbetten, Lebenszyklus- und Interaktions-Events abonnieren, dynamische Daten über Flow-Variablen übergeben, Interaktionen mit URL-Parametern verfolgen und das Chat-Fenster programmatisch steuern.

Dieser Leitfaden behandelt jeden Aspekt der JS API mit Codebeispielen, die Sie kopieren und an Ihr Projekt anpassen können.

Integrationscode (v2)

Wenn Sie einen Chatbot in FlowHunt erstellen, erhalten Sie ein Integrations-Snippet. Kopieren Sie es und fügen Sie es in Ihr HTML direkt vor dem schließenden </body>-Tag ein:

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

Ersetzen Sie YOUR_CHATBOT_ID und YOUR_WORKSPACE_ID durch die Werte aus Ihrem FlowHunt-Dashboard. Die Chatbot-ID im globalen Variablennamen (window.FHChatbot_YOUR_CHATBOT_ID) verwendet Unterstriche anstelle von Bindestrichen.

Konfiguration mit setConfig() überschreiben

Bevor Sie init() aufrufen, können Sie die Standard-Chatbot-Einstellungen mit setConfig() überschreiben:

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

Verfügbare Konfigurationsoptionen

OptionTypeBeschreibung
headerTitlestringBenutzerdefinierter Header-Titeltext
maxWindowWidthstringMaximale Breite des Chat-Fensters (z. B. '700px')
maxWindowHeightstringMaximale Höhe des Chat-Fensters
inputPlaceholderstringPlatzhaltertext für das Nachrichteneingabefeld
showChatButtonbooleanStandard-Schwebenden-Chat-Button anzeigen oder ausblenden
openChatPanelbooleanChat-Panel beim Seitenaufruf automatisch öffnen
flowVariablesobjectSchlüssel-Wert-Paare mit benutzerdefinierten Daten, die an den Flow übergeben werden
urlSuffixstringAbfragezeichenfolge, die an alle vom Chatbot generierten URLs angehängt wird
cookieConsentbooleanSitzungspersistenz über Cookies aktivieren
embeddedstringEingebetteten Modus aktivieren (kein Schließen-Button)
themestringDesignmodus
Logo

Bereit, Ihr Geschäft zu erweitern?

Starten Sie heute Ihre kostenlose Testversion und sehen Sie innerhalb weniger Tage Ergebnisse.

Demo anfragen Anmelden

Flow-Variablen: Dynamische Daten übergeben

Flow-Variablen ermöglichen es Ihnen, benutzerdefinierte Daten von Ihrer Website in den Chatbot-Flow zu senden. Dies ermöglicht personalisierte Gespräche basierend auf dem Benutzerkontext.

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

Einmal festgelegt, sind diese Variablen in Ihrer Chatbot-Flow-Logik zugänglich, sodass Sie Antworten personalisieren, Gespräche weiterleiten oder Kontext an KI-Agenten übergeben können.

URL-Suffix: Chatbot-Interaktionen verfolgen

Der Parameter urlSuffix hängt eine Abfragezeichenfolge an jede vom Chatbot generierte URL an. Dies ist nützlich, um chatbot-bezogenen Traffic in Analysetools zu verfolgen:

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

Anwendungsfälle:

  • Konversionen verfolgen von Chatbot-Interaktionen in Google Analytics.
  • Benutzerverhalten analysieren nach der Interaktion mit dem Chatbot.
  • Kampagnen zuordnen, die das Chatbot-Engagement fördern.

Event-Referenz

Die FlowHunt JS API löst 10 benutzerdefinierte Events auf dem window-Objekt aus. Alle Events verwenden die CustomEvent -API mit bubbles: true und composed: true.

onFHChatbotReady

Wird ausgelöst, wenn das Chatbot-Widget vollständig gerendert und einsatzbereit ist.

  • Event-Daten: Keine
  • Wann: Nachdem das Widget-DOM eingehängt und der Chat-Button sichtbar ist.

onFHChatbotSessionCreated

Wird ausgelöst, wenn eine neue Chat-Sitzung auf dem Server erstellt wird. Wird auch beim Neustart der Sitzung ausgelöst.

  • Event-Daten: Keine
  • Wann: Nach einem erfolgreichen API-Aufruf zur Sitzungserstellung.

onFHChatbotWindowOpened

Wird ausgelöst, wenn der Benutzer das Chat-Fenster öffnet.

  • Event-Daten: Keine
  • Wann: Das Chat-Panel wird sichtbar.
  • Hinweis: Wird im eingebetteten Modus nicht ausgelöst.

onFHChatbotWindowClosed

Wird ausgelöst, wenn der Benutzer das Chat-Fenster schließt.

  • Event-Daten: Keine
  • Wann: Das Chat-Panel wird ausgeblendet.
  • Hinweis: Wird im eingebetteten Modus nicht ausgelöst.

onFHMessageSent

Wird ausgelöst, wenn der Benutzer eine Nachricht sendet.

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

onFHMessageReceived

Wird ausgelöst, wenn der Chatbot eine Antwort empfängt und anzeigt.

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

Das Feld sender ist optional und nur vorhanden, wenn ein menschlicher Agent beteiligt ist.

onFHFormDataSent

Wird ausgelöst, wenn der Benutzer Formulardaten über den Chatbot übermittelt.

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

onFHFeedback

Wird ausgelöst, wenn ein Benutzer eine Daumen-hoch- oder Daumen-runter-Bewertung zu einer Chatbot-Nachricht abgibt.

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

Der Wert von feedback ist "P" für positiv (Daumen hoch) oder "N" für negativ (Daumen runter).

onFHToolCall

Wird ausgelöst, wenn ein Tool oder eine Aktion während der Flow-Verarbeitung ausgeführt wird.

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

Hinweis: Wird nur in den Modi flowAssistant und flowAssistantV3 ausgelöst, nicht im Standard-Chatbot-Modus.

onFHError

Wird ausgelöst, wenn während des Chatbot-Betriebs ein Fehler auftritt.

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

Events abonnieren

Es gibt zwei Möglichkeiten, Chatbot-Events zu abonnieren.

Methode 1: Window-Event-Listener

Verwenden Sie window.addEventListener überall auf Ihrer Seite. Dies funktioniert auch, bevor der Chatbot geladen wurde:

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

Um ein Event nicht mehr abzuhören, verwenden Sie removeEventListener mit derselben Funktionsreferenz:

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

Innerhalb des init()-Callbacks verwenden Sie die integrierten Methoden des Chatbot-Managers:

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

Referenz der Manager-Methoden

MethodParametersBeschreibung
onSessionCreated(fn)fn: () => voidAuf Sitzungserstellung lauschen
onWindowOpened(fn)fn: () => voidAuf Fensteröffnung lauschen
onWindowClosed(fn)fn: () => voidAuf Fensterschließung lauschen
onMessageSent(fn)fn: (event) => voidAuf Benutzernachrichten lauschen
onMessageReceived(fn)fn: (event) => voidAuf Bot-Antworten lauschen
onFormDataSent(fn)fn: (event) => voidAuf Formularübermittlungen lauschen
onFeedback(fn)fn: (event) => voidAuf Benutzerfeedback lauschen
onToolCall(fn)fn: (event) => voidAuf Tool-Ausführungen lauschen
onError(fn)fn: (event) => voidAuf Fehler lauschen
openChat()—Öffnet das Chat-Panel
closeChat()—Schließt das Chat-Panel

Benutzerdefinierte Chat-Aktivierung: Button ausblenden und bei Klick öffnen

Um vollständig zu kontrollieren, wann der Chatbot erscheint, blenden Sie den standardmäßigen schwebenden Button aus und öffnen Sie den Chat programmatisch — zum Beispiel über Ihren eigenen benutzerdefinierten Button.

Vollständiges Beispiel

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

Benutzerdefinierten Button erst anzeigen, wenn der Chatbot bereit ist

Sie können die versteckte Aktivierung mit Event-Listenern kombinieren, um erweiterte Interaktionen zu erstellen:

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

Vollständiges Integrationsbeispiel

Ein vollständiges Arbeitsbeispiel, das Konfigurationsüberschreibungen, Event-Tracking und benutzerdefinierte Chat-Aktivierung zusammen demonstriert:

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

Häufig gestellte Fragen

Welche Events kann ich mit der FlowHunt JS API abhören?

Die FlowHunt JS API sendet 10 Events: onFHChatbotReady, onFHChatbotSessionCreated, onFHChatbotWindowOpened, onFHChatbotWindowClosed, onFHMessageSent, onFHMessageReceived, onFHFormDataSent, onFHFeedback, onFHToolCall und onFHError. Sie können diese über window.addEventListener oder über die Callback-Methoden des Chatbot-Managers abonnieren.

Wie kann ich den Standard-Chat-Button ausblenden und den Chatbot programmatisch öffnen?

Verwenden Sie die Konfigurationsoption showChatButton: false, um den Standard-Button auszublenden, und rufen Sie dann chatbotManager.openChat() auf, um den Chatbot nach Ihren eigenen Bedingungen zu öffnen — beispielsweise bei einem Klick auf einen benutzerdefinierten Button.

Was ist der Unterschied zwischen den Manager-Callback-Methoden und window.addEventListener?

Beide Ansätze funktionieren. Die Manager-Callback-Methoden (z. B. chatbotManager.onMessageSent(fn)) werden innerhalb des init-Callbacks aufgerufen und sind an die Manager-Instanz gebunden. Der window.addEventListener-Ansatz (z. B. window.addEventListener('onFHMessageSent', fn)) kann überall auf Ihrer Seite eingerichtet werden, sogar bevor der Chatbot geladen wird.

Wie kann ich benutzerdefinierte Daten mit Flow-Variablen an den Chatbot übergeben?

Verwenden Sie die Konfigurationsoption flowVariables in setConfig(), um Schlüssel-Wert-Paare wie Benutzer-ID, E-Mail oder Seiten-URL zu übergeben. Diese Variablen werden in Ihrem Chatbot-Flow für personalisierte Antworten verfügbar.

Welche Daten sind in Event-Handlern verfügbar?

Events, die Daten enthalten, stellen diese in event.detail.metadata bereit. Zum Beispiel enthält onFHMessageSent den Nachrichteninhalt und den Zeitstempel, onFHMessageReceived enthält die flow_id, message_id und den Nachrichtentext, und onFHFeedback enthält die message_id und ob das Feedback positiv oder negativ war.