"Jakie zdarzenia moge nasluchiwac za pomoca FlowHunt JS API?"

"FlowHunt JS API emituje 10 zdarzen: onFHChatbotReady, onFHChatbotSessionCreated, onFHChatbotWindowOpened, onFHChatbotWindowClosed, onFHMessageSent, onFHMessageReceived, onFHFormDataSent, onFHFeedback, onFHToolCall i onFHError. Mozesz je subskrybowac za pomoca window.addEventListener lub metod callback menedzera chatbota."

"Jak ukryc domyslny przycisk czatu i otworzyc chatbota programowo?"

"Uzyj opcji konfiguracyjnej showChatButton: false, aby ukryc domyslny przycisk, a nastepnie wywolaj chatbotManager.openChat(), aby otworzyc chatbota na wlasnych warunkach — na przyklad po kliknieciu wlasnego przycisku."

"Jaka jest roznica miedzy metodami callback menedzera a window.addEventListener?"

"Oba podejscia dzialaja. Metody callback menedzera (np. chatbotManager.onMessageSent(fn)) sa wywolywane wewnatrz callbacku init i sa powiazane z instancja menedzera. Podejscie window.addEventListener (np. window.addEventListener('onFHMessageSent', fn)) mozna skonfigurowac w dowolnym miejscu strony, nawet przed zaladowaniem chatbota."

"Jak przekazac niestandardowe dane do chatbota za pomoca zmiennych przeplywu?"

"Uzyj opcji konfiguracyjnej flowVariables w setConfig(), aby przekazac pary klucz-wartosc, takie jak identyfikator uzytkownika, adres e-mail lub adres URL strony. Zmienne te staja sie dostepne w przeplywach chatbota i umozliwiaja personalizowane odpowiedzi."

"Jakie dane sa dostepne w obslugach zdarzen?"

"Zdarzenia zawierajace dane przekazuja je w event.detail.metadata. Na przyklad onFHMessageSent zawiera tresc wiadomosci i znacznik czasu, onFHMessageReceived zawiera flow_id, message_id i tekst wiadomosci, a onFHFeedback zawiera message_id oraz informacje, czy opinia byla pozytywna czy negatywna."

FlowHunt JS API: Przewodnik integracji dla zaawansowanych uzytkownikow

Kompletna dokumentacja integracji FlowHunt JS API v2. Dowiedz sie, jak osadzic chatbota, subskrybowac wszystkie 10 zdarzen, uzywac zmiennych przeplywu, sledzic interakcje za pomoca parametrow URL i programowo sterowac oknem czatu.

FlowHunt JavaScript API Chatbot Integration

FlowHunt JS API daje pelna kontrole nad sposobem integracji chatbota z Twoja strona internetowa. Korzystajac z kodu integracyjnego v2, mozesz osadzic chatbota, subskrybowac zdarzenia cyklu zycia i interakcji, przekazywac dynamiczne dane za pomoca zmiennych przeplywu, sledzic interakcje za pomoca parametrow URL i programowo sterowac oknem czatu.

Ten przewodnik obejmuje kazdy aspekt JS API z przykladami kodu, ktore mozesz skopiowac i dostosowac do swojego projektu.

Kod integracyjny (v2)

Po utworzeniu chatbota w FlowHunt otrzymujesz fragment kodu integracyjnego. Skopiuj go i wklej do swojego HTML tuz przed zamykajacym tagiem </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>

Zastap YOUR_CHATBOT_ID i YOUR_WORKSPACE_ID wartosciami z panelu FlowHunt. Identyfikator chatbota w nazwie zmiennej globalnej (window.FHChatbot_YOUR_CHATBOT_ID) uzywa podkreslnikow zamiast myslnikow.

Nadpisywanie konfiguracji za pomoca setConfig()

Przed wywolaniem init() mozesz nadpisac domyslne ustawienia chatbota za pomoca 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>

Dostepne opcje konfiguracyjne

Option	Type	Opis
`headerTitle`	string	Niestandardowy tekst naglowka
`maxWindowWidth`	string	Maksymalna szerokosc okna czatu (np. `'700px'`)
`maxWindowHeight`	string	Maksymalna wysokosc okna czatu
`inputPlaceholder`	string	Tekst zastepczy pola wiadomosci
`showChatButton`	boolean	Pokaz lub ukryj domyslny plywajacy przycisk czatu
`openChatPanel`	boolean	Automatycznie otworz panel czatu przy ladowaniu strony
`flowVariables`	object	Pary klucz-wartosc z niestandardowymi danymi przekazywanymi do przeplywu
`urlSuffix`	string	Ciag zapytania dolaczany do wszystkich URL-i generowanych przez chatbota
`cookieConsent`	boolean	Wlacz trwalosc sesji za pomoca plikow cookie
`embedded`	string	Ustaw, aby wlaczyc tryb osadzony (bez przycisku zamykania)
`theme`	string	Tryb motywu

Zmienne przeplywu: Przekazywanie dynamicznych danych

Zmienne przeplywu umozliwiaja wysylanie niestandardowych danych z Twojej strony internetowej do przeplywu chatbota. Pozwala to na personalizowane rozmowy oparte na kontekscie uzytkownika.

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

Po ustawieniu zmienne te sa dostepne w logice przeplywu chatbota, co umozliwia personalizowanie odpowiedzi, kierowanie rozmow lub przekazywanie kontekstu do agentow AI.

Sufiks URL: Sledzenie interakcji chatbota

Parametr urlSuffix dolacza ciag zapytania do kazdego URL-a generowanego przez chatbota. Jest to przydatne do sledzenia ruchu generowanego przez chatbota w narzeddziach analitycznych:

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

Przypadki uzycia:

Sledzenie konwersji z interakcji chatbota w Google Analytics.
Analiza zachowan uzytkownikow po interakcji z chatbotem.
Przypisywanie kampanii, ktore napedzaja zaangazowanie w chatbota.

Dokumentacja zdarzen

FlowHunt JS API wysyla 10 niestandardowych zdarzen na obiekcie window. Wszystkie zdarzenia uzywaja API CustomEvent z ustawieniami bubbles: true i composed: true.

onFHChatbotReady

Uruchamiane, gdy widget chatbota zostal w pelni wyrenderowany i jest gotowy do uzycia.

Dane zdarzenia: Brak
Kiedy: Po zamontowaniu DOM widgetu i gdy przycisk czatu jest widoczny.

onFHChatbotSessionCreated

Uruchamiane, gdy na serwerze tworzona jest nowa sesja czatu. Uruchamiane rowniez przy ponownym uruchomieniu sesji.

Dane zdarzenia: Brak
Kiedy: Po udanym wywolaniu API tworzenia sesji.

onFHChatbotWindowOpened

Uruchamiane, gdy uzytkownik otwiera okno czatu.

Dane zdarzenia: Brak
Kiedy: Panel czatu staje sie widoczny.
Uwaga: Nie jest uruchamiane w trybie osadzonym.

onFHChatbotWindowClosed

Uruchamiane, gdy uzytkownik zamyka okno czatu.

Dane zdarzenia: Brak
Kiedy: Panel czatu jest ukrywany.
Uwaga: Nie jest uruchamiane w trybie osadzonym.

onFHMessageSent

Uruchamiane, gdy uzytkownik wysyla wiadomosc.

Dane zdarzenia (event.detail.metadata):

{
  "content": "Hello, I need help with...",
  "createdAt": "2026-02-19T10:30:00.000Z"
}

onFHMessageReceived

Uruchamiane, gdy chatbot odbiera i wyswietla odpowiedz.

Dane zdarzenia (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"
  }
}

Pole sender jest opcjonalne i wystepuje tylko wtedy, gdy zaangazowany jest ludzki agent.

onFHFormDataSent

Uruchamiane, gdy uzytkownik przesyla dane formularza przez chatbota.

Dane zdarzenia (event.detail.metadata):

{
  "objectData": { "name": "John", "email": "john@example.com" },
  "createdAt": "2026-02-19T10:31:00.000Z"
}

onFHFeedback

Uruchamiane, gdy uzytkownik daje ocene kciuk w gore lub kciuk w dol na wiadomosc chatbota.

Dane zdarzenia (event.detail.metadata):

{
  "message_id": "msg_456",
  "content": "Optional feedback text",
  "feedback": "P"
}

Wartosc feedback to "P" dla pozytywnej opinii (kciuk w gore) lub "N" dla negatywnej (kciuk w dol).

onFHToolCall

Uruchamiane, gdy narzedzie lub akcja jest wykonywana podczas przetwarzania przeplywu.

Dane zdarzenia (event.detail.metadata):

{
  "metadata": {
    "flow_id": "abc123",
    "message_id": "msg_789",
    "message": "Calling search API..."
  },
  "createdAt": "2026-02-19T10:32:00.000Z"
}

Uwaga: Uruchamiane tylko w trybach flowAssistant i flowAssistantV3, nie w standardowym trybie chatbota.

onFHError

Uruchamiane, gdy podczas dzialania chatbota wystapi blad.

Dane zdarzenia (event.detail.metadata):

{
  "metadata": {
    "flow_id": "abc123",
    "message_id": "msg_err",
    "message": "Flow execution failed"
  },
  "createdAt": "2026-02-19T10:33:00.000Z"
}

Subskrybowanie zdarzen

Istnieja dwa sposoby subskrybowania zdarzen chatbota.

Metoda 1: Nasluchiwacze zdarzen okna

Uzyj window.addEventListener w dowolnym miejscu swojej strony. Dziala to nawet przed zaladowaniem chatbota:

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

Aby przestac nasluchiwac zdarzenia, uzyj removeEventListener z ta sama referencja funkcji:

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

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

Metoda 2: Metody callback menedzera

Wewnatrz callbacku init() uzyj wbudowanych metod menedzera chatbota:

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

Dokumentacja metod menedzera

Method	Parameters	Opis
`onSessionCreated(fn)`	`fn: () => void`	Nasluchuj tworzenia sesji
`onWindowOpened(fn)`	`fn: () => void`	Nasluchuj otwierania okna
`onWindowClosed(fn)`	`fn: () => void`	Nasluchuj zamykania okna
`onMessageSent(fn)`	`fn: (event) => void`	Nasluchuj wiadomosci uzytkownika
`onMessageReceived(fn)`	`fn: (event) => void`	Nasluchuj odpowiedzi bota
`onFormDataSent(fn)`	`fn: (event) => void`	Nasluchuj wysylania formularzy
`onFeedback(fn)`	`fn: (event) => void`	Nasluchuj opinii uzytkownikow
`onToolCall(fn)`	`fn: (event) => void`	Nasluchuj wykonan narzedzi
`onError(fn)`	`fn: (event) => void`	Nasluchuj bledow
`openChat()`	—	Otwiera panel czatu
`closeChat()`	—	Zamyka panel czatu

Niestandardowa aktywacja czatu: Ukryj przycisk i otworz po kliknieciu

Aby w pelni kontrolowac, kiedy chatbot sie pojawia, ukryj domyslny plywajacy przycisk i otworz czat programowo — na przyklad z wlasnego niestandardowego przycisku.

Pelny przyklad

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

Pokaz niestandardowy przycisk dopiero gdy chatbot jest gotowy

Mozesz polaczyc ukryta aktywacje z nasluchiwaczami zdarzen, aby tworzyc zaawansowane interakcje:

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

Kompletny przyklad integracji

Pelny dzialajacy przyklad demonstrujacy nadpisywanie konfiguracji, sledzenie zdarzen i niestandardowa aktywacje czatu w jednym:

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

Najczęściej zadawane pytania

Jakie zdarzenia moge nasluchiwac za pomoca FlowHunt JS API?: FlowHunt JS API emituje 10 zdarzen: onFHChatbotReady, onFHChatbotSessionCreated, onFHChatbotWindowOpened, onFHChatbotWindowClosed, onFHMessageSent, onFHMessageReceived, onFHFormDataSent, onFHFeedback, onFHToolCall i onFHError. Mozesz je subskrybowac za pomoca window.addEventListener lub metod callback menedzera chatbota.
Jak ukryc domyslny przycisk czatu i otworzyc chatbota programowo?: Uzyj opcji konfiguracyjnej showChatButton: false, aby ukryc domyslny przycisk, a nastepnie wywolaj chatbotManager.openChat(), aby otworzyc chatbota na wlasnych warunkach — na przyklad po kliknieciu wlasnego przycisku.
Jaka jest roznica miedzy metodami callback menedzera a window.addEventListener?: Oba podejscia dzialaja. Metody callback menedzera (np. chatbotManager.onMessageSent(fn)) sa wywolywane wewnatrz callbacku init i sa powiazane z instancja menedzera. Podejscie window.addEventListener (np. window.addEventListener('onFHMessageSent', fn)) mozna skonfigurowac w dowolnym miejscu strony, nawet przed zaladowaniem chatbota.
Jak przekazac niestandardowe dane do chatbota za pomoca zmiennych przeplywu?: Uzyj opcji konfiguracyjnej flowVariables w setConfig(), aby przekazac pary klucz-wartosc, takie jak identyfikator uzytkownika, adres e-mail lub adres URL strony. Zmienne te staja sie dostepne w przeplywach chatbota i umozliwiaja personalizowane odpowiedzi.
Jakie dane sa dostepne w obslugach zdarzen?: Zdarzenia zawierajace dane przekazuja je w event.detail.metadata. Na przyklad onFHMessageSent zawiera tresc wiadomosci i znacznik czasu, onFHMessageReceived zawiera flow_id, message_id i tekst wiadomosci, a onFHFeedback zawiera message_id oraz informacje, czy opinia byla pozytywna czy negatywna.