"Ce evenimente pot asculta cu FlowHunt JS API?"

"FlowHunt JS API emite 10 evenimente: onFHChatbotReady, onFHChatbotSessionCreated, onFHChatbotWindowOpened, onFHChatbotWindowClosed, onFHMessageSent, onFHMessageReceived, onFHFormDataSent, onFHFeedback, onFHToolCall si onFHError. Va puteti abona la acestea folosind window.addEventListener sau prin metodele callback ale managerului de chatbot."

"Cum ascund butonul implicit de chat si deschid chatbot-ul programatic?"

"Folositi optiunea de configurare showChatButton: false pentru a ascunde butonul implicit, apoi apelati chatbotManager.openChat() pentru a deschide chatbot-ul in propriile conditii — de exemplu, la click pe un buton personalizat."

"Care este diferenta dintre metodele callback ale managerului si window.addEventListener?"

"Ambele abordari functioneaza. Metodele callback ale managerului (de ex. chatbotManager.onMessageSent(fn)) sunt apelate in interiorul callback-ului init si sunt legate de instanta managerului. Abordarea cu window.addEventListener (de ex. window.addEventListener('onFHMessageSent', fn)) poate fi configurata oriunde in pagina, chiar si inainte de incarcarea chatbot-ului."

"Cum trimit date personalizate catre chatbot folosind variabile de flux?"

"Folositi optiunea de configurare flowVariables in setConfig() pentru a trimite perechi cheie-valoare precum ID-ul utilizatorului, email-ul sau URL-ul paginii. Aceste variabile devin disponibile in fluxul chatbot-ului pentru raspunsuri personalizate."

"Ce date sunt disponibile in handlerele de evenimente?"

"Evenimentele care transporta date le includ in event.detail.metadata. De exemplu, onFHMessageSent include continutul mesajului si marcajul temporal, onFHMessageReceived include flow_id, message_id si textul mesajului, iar onFHFeedback include message_id si daca feedback-ul a fost pozitiv sau negativ."

FlowHunt JS API: Ghid de integrare pentru utilizatori avansati

Referinta completa pentru integrarea FlowHunt JS API v2. Aflati cum sa incorporati chatbot-ul, sa va abonati la toate cele 10 evenimente, sa utilizati variabile de flux, sa urmariti interactiunile cu parametri URL si sa controlati fereastra de chat programatic.

FlowHunt JavaScript API Chatbot Integration

FlowHunt JS API va ofera control complet asupra modului in care chatbot-ul se integreaza cu site-ul dvs. web. Folosind codul de integrare v2, puteti incorpora chatbot-ul, va puteti abona la evenimentele de ciclu de viata si interactiune, puteti trimite date dinamice prin variabile de flux, urmari interactiunile cu parametri URL si controla fereastra de chat programatic.

Acest ghid acopera fiecare aspect al JS API cu exemple de cod pe care le puteti copia si adapta proiectului dvs.

Cod de integrare (v2)

Cand creati un chatbot in FlowHunt, primiti un snippet de integrare. Copiati-l si lipiti-l in HTML-ul dvs. chiar inainte de tag-ul de inchidere </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>

Inlocuiti YOUR_CHATBOT_ID si YOUR_WORKSPACE_ID cu valorile din panoul de control FlowHunt. ID-ul chatbot-ului din numele variabilei globale (window.FHChatbot_YOUR_CHATBOT_ID) foloseste underscore in loc de cratima.

Suprascrierea configuratiei cu setConfig()

Inainte de a apela init(), puteti suprascrie setarile implicite ale chatbot-ului folosind 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>

Optiuni de configurare disponibile

Option	Type	Description
`headerTitle`	string	Text personalizat pentru titlul din antet
`maxWindowWidth`	string	Latimea maxima a ferestrei de chat (de ex. `'700px'`)
`maxWindowHeight`	string	Inaltimea maxima a ferestrei de chat
`inputPlaceholder`	string	Text substituent pentru campul de introducere a mesajului
`showChatButton`	boolean	Afisarea sau ascunderea butonului flotant implicit de chat
`openChatPanel`	boolean	Deschiderea automata a panoului de chat la incarcarea paginii
`flowVariables`	object	Perechi cheie-valoare de date personalizate trimise catre flux
`urlSuffix`	string	Sir de interogare adaugat la toate URL-urile generate de chatbot
`cookieConsent`	boolean	Activarea persistentei sesiunii prin cookie-uri
`embedded`	string	Setare pentru activarea modului incorporat (fara buton de inchidere)
`theme`	string	Modul temei

Variabile de flux: Trimiterea datelor dinamice

Variabilele de flux va permit sa trimiteti date personalizate de pe site-ul dvs. web catre fluxul chatbot-ului. Aceasta permite conversatii personalizate bazate pe contextul utilizatorului.

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

Odata setate, aceste variabile sunt accesibile in logica fluxului chatbot-ului, permitandu-va sa personalizati raspunsurile, sa directionati conversatiile sau sa transmiteti context agentilor AI.

URL Suffix: Urmarirea interactiunilor chatbot-ului

Parametrul urlSuffix adauga un sir de interogare la fiecare URL generat de chatbot. Acesta este util pentru urmarirea traficului provenit din chatbot in instrumentele de analiza:

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

Cazuri de utilizare:

Urmarirea conversiilor din interactiunile chatbot-ului in Google Analytics.
Analiza comportamentului utilizatorilor dupa interactiunea cu chatbot-ul.
Atribuirea campaniilor care stimuleaza implicarea chatbot-ului.

Referinta evenimente

FlowHunt JS API distribuie 10 evenimente personalizate pe obiectul window. Toate evenimentele folosesc API-ul CustomEvent cu bubbles: true si composed: true.

onFHChatbotReady

Declansat cand widget-ul chatbot-ului s-a randat complet si este gata de utilizare.

Date eveniment: Niciuna
Cand: Dupa montarea DOM-ului widget-ului si afisarea butonului de chat.

onFHChatbotSessionCreated

Declansat cand se creeaza o noua sesiune de chat pe server. Se declanseaza si la repornirea sesiunii.

Date eveniment: Niciuna
Cand: Dupa un apel API reusit de creare a sesiunii.

onFHChatbotWindowOpened

Declansat cand utilizatorul deschide fereastra de chat.

Date eveniment: Niciuna
Cand: Panoul de chat devine vizibil.
Nota: Nu se declanseaza in modul incorporat.

onFHChatbotWindowClosed

Declansat cand utilizatorul inchide fereastra de chat.

Date eveniment: Niciuna
Cand: Panoul de chat este ascuns.
Nota: Nu se declanseaza in modul incorporat.

onFHMessageSent

Declansat cand utilizatorul trimite un mesaj.

Date eveniment (event.detail.metadata):

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

onFHMessageReceived

Declansat cand chatbot-ul primeste si afiseaza un raspuns.

Date eveniment (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"
  }
}

Campul sender este optional si este prezent doar cand este implicat un agent uman.

onFHFormDataSent

Declansat cand utilizatorul trimite date de formular prin chatbot.

Date eveniment (event.detail.metadata):

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

onFHFeedback

Declansat cand un utilizator ofera feedback pozitiv sau negativ la un mesaj al chatbot-ului.

Date eveniment (event.detail.metadata):

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

Valoarea feedback este "P" pentru pozitiv (like) sau "N" pentru negativ (dislike).

onFHToolCall

Declansat cand un instrument sau o actiune este executata in timpul procesarii fluxului.

Date eveniment (event.detail.metadata):

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

Nota: Se declanseaza doar in modurile flowAssistant si flowAssistantV3, nu in modul standard de chatbot.

onFHError

Declansat cand apare o eroare in timpul functionarii chatbot-ului.

Date eveniment (event.detail.metadata):

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

Abonarea la evenimente

Exista doua modalitati de a va abona la evenimentele chatbot-ului.

Metoda 1: Ascultatori de evenimente pe fereastra

Folositi window.addEventListener oriunde in pagina dvs. Aceasta functioneaza chiar si inainte de incarcarea chatbot-ului:

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

Pentru a opri ascultarea unui eveniment, folositi removeEventListener cu aceeasi referinta de functie:

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: Metodele callback ale managerului

In interiorul callback-ului init(), folositi metodele incorporate ale managerului de 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);
  });
});

Referinta metode manager

Method	Parameters	Description
`onSessionCreated(fn)`	`fn: () => void`	Ascultare pentru crearea sesiunii
`onWindowOpened(fn)`	`fn: () => void`	Ascultare pentru deschiderea ferestrei
`onWindowClosed(fn)`	`fn: () => void`	Ascultare pentru inchiderea ferestrei
`onMessageSent(fn)`	`fn: (event) => void`	Ascultare pentru mesajele utilizatorului
`onMessageReceived(fn)`	`fn: (event) => void`	Ascultare pentru raspunsurile bot-ului
`onFormDataSent(fn)`	`fn: (event) => void`	Ascultare pentru trimiterea formularelor
`onFeedback(fn)`	`fn: (event) => void`	Ascultare pentru feedback-ul utilizatorului
`onToolCall(fn)`	`fn: (event) => void`	Ascultare pentru executarea instrumentelor
`onError(fn)`	`fn: (event) => void`	Ascultare pentru erori
`openChat()`	—	Deschide panoul de chat
`closeChat()`	—	Inchide panoul de chat

Activare personalizata a chatului: Ascunderea butonului si deschiderea la click

Pentru a controla complet cand apare chatbot-ul, ascundeti butonul flotant implicit si deschideti chatul programatic — de exemplu, de la propriul buton personalizat.

Exemplu complet

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

Afisarea unui buton personalizat doar cand chatbot-ul este gata

Puteti combina activarea ascunsa cu ascultatorii de evenimente pentru a crea interactiuni avansate:

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

Exemplu complet de integrare

Un exemplu complet functional care demonstreaza suprascrierea configuratiei, urmarirea evenimentelor si activarea personalizata a chatului impreuna:

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

Întrebări frecvente

Ce evenimente pot asculta cu FlowHunt JS API?: FlowHunt JS API emite 10 evenimente: onFHChatbotReady, onFHChatbotSessionCreated, onFHChatbotWindowOpened, onFHChatbotWindowClosed, onFHMessageSent, onFHMessageReceived, onFHFormDataSent, onFHFeedback, onFHToolCall si onFHError. Va puteti abona la acestea folosind window.addEventListener sau prin metodele callback ale managerului de chatbot.
Cum ascund butonul implicit de chat si deschid chatbot-ul programatic?: Folositi optiunea de configurare showChatButton: false pentru a ascunde butonul implicit, apoi apelati chatbotManager.openChat() pentru a deschide chatbot-ul in propriile conditii — de exemplu, la click pe un buton personalizat.
Care este diferenta dintre metodele callback ale managerului si window.addEventListener?: Ambele abordari functioneaza. Metodele callback ale managerului (de ex. chatbotManager.onMessageSent(fn)) sunt apelate in interiorul callback-ului init si sunt legate de instanta managerului. Abordarea cu window.addEventListener (de ex. window.addEventListener('onFHMessageSent', fn)) poate fi configurata oriunde in pagina, chiar si inainte de incarcarea chatbot-ului.
Cum trimit date personalizate catre chatbot folosind variabile de flux?: Folositi optiunea de configurare flowVariables in setConfig() pentru a trimite perechi cheie-valoare precum ID-ul utilizatorului, email-ul sau URL-ul paginii. Aceste variabile devin disponibile in fluxul chatbot-ului pentru raspunsuri personalizate.
Ce date sunt disponibile in handlerele de evenimente?: Evenimentele care transporta date le includ in event.detail.metadata. De exemplu, onFHMessageSent include continutul mesajului si marcajul temporal, onFHMessageReceived include flow_id, message_id si textul mesajului, iar onFHFeedback include message_id si daca feedback-ul a fost pozitiv sau negativ.