FlowHunt JS API: Advanced Chatbot Customization

Unlock advanced FlowHunt chatbot features: personalize with flow variables, track with URL suffixes, use event handlers, and control chat activation for a tailored user experience.

Flowhunt is packed with strong features that allow deep customization of how your chatbot behaves and seamlessly integrates with your site or application. In this page, you learn to perform some advanced customizations – flow variables, URL parameters, event-driven callbacks, and a custom chat activation logic.

Flow Variables: Personalize the Chat Experience

Flow variables provide a means of passing in dynamic data to the chatbot so that it may be truly personalized. You can store anything inside these variables; it could be user data, session data, or any information of relevance.

How to Use flowVariable

The flowVariable is part of FHChatbot.initChatbot() configuration. It’s an object where each key-value pair defines a variable and its value. Example – Passing user’s IP address and user id:

<script type="text/javascript" id="fh-chatbot-script-8f1fd880-8e9c-4cb1-a1f2-291c0329612b">
(function(d, src, c) { 
  var t=d.scripts[d.scripts.length - 1],s=d.createElement('script');
  s.async=true;s.src=src;s.onload=s.onreadystatechange=function(){
    var rs=this.readyState;
    if(rs&&(rs!='complete')&&(rs!='loaded')){return;}
    c(this);
  };
  t.parentElement.insertBefore(s,t.nextSibling);
})(document,
  'https://app.flowhunt.io/fh-chat-widget.js',
  function(e){ 
    FHChatbot.initChatbot({
      chatbotId: '8f1fd880-8e9c-4cb1-a1f2-291c0329612b',
      workspaceId: 'e31db667-893b-4e47-92c3-bb1f93c1b594',
      headerTitle: 'URLsLab FAQ Generator',
      maxWindowWidth: '700px',
      "flowVariable": {
        "ip": /* Code to obtain IP Address */ ,
        "userId":  /* Code to obtain User ID */
      }
    });
  }
);
</script>

Important Notes:

  • Replace /* Code to obtain IP Address */ and /* Code to obtain User ID */ with your actual logic to retrieve these values from your system. This often involves accessing server-side variables, local storage, or relying on other authentication methods.
  • Once passed, these variables are available within your chatbot logic, which allows for dynamic responses and personalized workflows.
  • The chatbot logic can read and use these variables to personalize conversations and make them more context-aware.

urlSuffix: Track and Analyze Chatbot Interactions

The urlSuffix parameter allows you to append a query string to the end of every URL called by the chatbot. This is invaluable for tracking the origin and effectiveness of your chatbot interactions using analytics tools like Google Analytics.

How to Use urlSuffix

Simply set the urlSuffix property to your desired query string, as follows:

<script type="text/javascript" id="fh-chatbot-script-8f1fd880-8e9c-4cb1-a1f2-291c0329612b">
(function(d, src, c) { 
  var t=d.scripts[d.scripts.length - 1],s=d.createElement('script');
  s.async=true;s.src=src;s.onload=s.onreadystatechange=function(){
    var rs=this.readyState;
    if(rs&&(rs!='complete')&&(rs!='loaded')){return;}
    c(this);
  };
  t.parentElement.insertBefore(s,t.nextSibling);
})(document,
  'https://app.flowhunt.io/fh-chat-widget.js',
  function(e){ 
    FHChatbot.initChatbot({
      chatbotId: '8f1fd880-8e9c-4cb1-a1f2-291c0329612b',
      workspaceId: 'e31db667-893b-4e47-92c3-bb1f93c1b594',
      headerTitle: 'URLsLab FAQ Generator',
      maxWindowWidth: '700px',
      "urlSUffix": "?utm_source=your-custom-source"
    });
  }
);
</script>

In this example, ?utm_source=your-custom-source will be appended to all URLs initiated by the chatbot, allowing you to track chatbot traffic in your analytics platform.

Benefits

  • Track Conversions: Monitor which chatbot interactions lead to the most conversions on your website.
  • Analyze User Behavior: Understand how users navigate your site after engaging with the chatbot.
  • Attribute Campaigns: Measure the effectiveness of campaigns that encourage users to engage with the chatbot.

Event Handlers: React to Chatbot Actions

Flowhunt allows you to set up event handlers that trigger custom functions when certain events occur in the chatbot. These handlers give you precise control over the user experience. The main event handlers include:

  • onSessionCreated: Triggered when a new chatbot session is initiated (restarting the session also counts!).
  • onWindowOpened: Triggered when the chatbot window is opened.
  • onWindowClosed: Triggered when the chatbot window is closed.
  • onError: Triggered when there’s an error in the chatbot.
  • onMessageReceived: Triggered when the bot sends a message and when a user sends an input.
  • onMessageSent: Triggered when the user sends a message.

How to Use Event Handlers

You can set up handlers using the fhChatbot variable returned by FHChatbot.initChatbot, and add listeners like fhChatbot.onSessionCreated(). Here is an example:

<script type="text/javascript" id="fh-chatbot-script-8f1fd880-8e9c-4cb1-a1f2-291c0329612b">
// catch event when chatbot is ready on your page
window.addEventListener("onFHChatbotReady", (e) => {
  console.log("Chatbot is ready, chat button should be visible at this time ready to be clicked.");
});

(function(d, src, c) { 
  var t=d.scripts[d.scripts.length - 1],s=d.createElement('script');
  s.async=true;s.src=src;s.onload=s.onreadystatechange=function(){
    var rs=this.readyState;
    if(rs&&(rs!='complete')&&(rs!='loaded')){return;}
    c(this);
  };
  t.parentElement.insertBefore(s,t.nextSibling);
})(document,
  'https://app.flowhunt.io/fh-chat-widget.js',
  function(e){ 
    const fhChatbot = FHChatbot.initChatbot({
      chatbotId: '8f1fd880-8e9c-4cb1-a1f2-291c0329612b',
      workspaceId: 'e31db667-893b-4e47-92c3-bb1f93c1b594',
      headerTitle: 'URLsLab FAQ Generator',
      maxWindowWidth: '700px',
      "urlSUffix": "?utm_source=asdfsdfgsdg"
    }); 
    
    fhChatbot.onSessionCreated(function () {
      // Custom logic when the session is created, could fire API calls, or store data
      console.log("session started");
    });
    
    fhChatbot.onWindowOpened(function () {
      // custom logic when the window opens, or show some content above the chat
      console.log("window opened");
    });
    
    fhChatbot.onWindowClosed(function () {
      // custom logic when the window is closed, or show some content above the chat
      console.log("window closed");
    });
    
    fhChatbot.onError(function (e) {
      // custom logic when an error is fired, could track it on error tracking tool.
      console.log(e.metadata);
      console.log("window error");
    });
    
    fhChatbot.onMessageReceived(function (e) {
      // custom logic when the bot answered.
      console.log("chatbot answered");
    });
    
    fhChatbot.onMessageSent(function (e) {
      // custom logic when the user sent an input.
      console.log("user sent an input");
    });
  }
);
</script>

Each event handler function can execute custom logic to make your chatbot behave dynamically to your user’s behavior.

Use Cases:

  • Analytics and Reporting: Track session starts and chatbot usage using onSessionStart and other events to send valuable metrics.
  • Dynamic UI Updates: Modify your page based on chatbot events (e.g. display a different message when chat is active).
  • Error Handling: Catch and respond to chatbot errors, enhancing user experience.
  • Custom User Flows: Implement custom logic based on user interactions with the chat.

Custom Chat Activation: Open and Close on Your Terms

By setting showChatButton: false, you can hide the default chat button. Then, you can programmatically open or close the chatbot window based on your own custom logic. This gives you ultimate control of the user interface.

How to Use Custom Activation

  1. Disable the Default Button: In your FHChatbot.initChatbot() options, add: showChatButton: false.
  2. Control Programmatically: Use the fhChatbot.openChat() and fhChatbot.closeChat() methods to control visibility based on your custom events.
<script type="text/javascript" id="fh-chatbot-script-8f1fd880-8e9c-4cb1-a1f2-291c0329612b">
(function(d, src, c) { 
  var t=d.scripts[d.scripts.length - 1],s=d.createElement('script');
  s.async=true;s.src=src;s.onload=s.onreadystatechange=function(){
    var rs=this.readyState;
    if(rs&&(rs!='complete')&&(rs!='loaded')){return;}
    c(this);
  };
  t.parentElement.insertBefore(s,t.nextSibling);
})(document,
  'https://app.flowhunt.io/fh-chat-widget.js',
  function(e){ 
    const fhChatbot = FHChatbot.initChatbot({
      chatbotId: '8f1fd880-8e9c-4cb1-a1f2-291c0329612b',
      workspaceId: 'e31db667-893b-4e47-92c3-bb1f93c1b594',
      headerTitle: 'URLsLab FAQ Generator',
      maxWindowWidth: '700px',
      "urlSUffix": "?utm_source=asdfsdfgsdg",
      "showChatButton": false
    }); 
    
    // Example: if user clicks on a button 
    const customChatButton = document.getElementById("myCustomChatButton")
    customChatButton.addEventListener("click", () => {
      fhChatbot.openChat();
    });

    // Example: if user closes by using a custom close button
    const customCloseChatButton = document.getElementById("myCustomCloseChatButton")
    customCloseChatButton.addEventListener("click", () => {
      fhChatbot.closeChat();
    });
  }
);
</script>

In this example, we added listeners to custom buttons to either open or close the chat.

Benefits:

  • Custom Design: Integrate the chatbot with your website’s look and feel, using a custom button or other triggers to initiate the chat.
  • User Flow Control: Launch the chatbot at specific points during the user journey, enhancing contextual support.
  • Strategic Placement: Use animations or other visual cues to draw user attention to the chatbot when the time is right.

By using flow variables, URL suffixes, event handlers, and custom chat activation, you can create highly customized and engaging chatbot experiences with Flowhunt. These advanced options provide you with the tools to fine-tune your chatbot to perfectly match your business needs and your users’ expectations.

Frequently asked questions

What are flow variables in FlowHunt?

Flow variables allow you to pass dynamic data—such as user or session information—into your FlowHunt chatbot. This enables personalized and context-aware conversations tailored to each user.

How can I track chatbot interactions using FlowHunt?

Use the urlSuffix parameter to append custom query strings to every URL called by the chatbot. This makes it easy to track chatbot-originated traffic and conversions in analytics tools like Google Analytics.

What event handlers are available in the FlowHunt JS API?

FlowHunt supports event handlers such as onSessionCreated, onWindowOpened, onWindowClosed, onError, onMessageReceived, and onMessageSent, giving you full control over chatbot-driven user interactions.

How do I activate or control the FlowHunt chatbot programmatically?

Set 'showChatButton' to false to hide the default button, then use fhchatbot.openChat() and fhChatbot.closeChat() to open or close the chatbot based on your custom logic or user actions.

What are the benefits of advanced chatbot customization in FlowHunt?

Advanced customization lets you personalize user journeys, integrate analytics, trigger dynamic actions, and seamlessly match the chatbot experience to your site's design and business needs.

Try FlowHunt’s Advanced Chatbot Customization

Take your chatbot to the next level with FlowHunt's advanced JS API features. Personalize, analyze, and control every aspect of your AI chatbot.

Schedule a Demo Try it Now

Learn more