Live Chat Widget JavaScript API Guide

This guide provides an overview of the JavaScript API for configuring and managing the Live Chat Widget. With this API, you can pre-fill user details, manage widget behavior, and customize chat interactions dynamically.

Overview

This documentation covers:

• Properties: Define user details such as email, name, and phone number. Configure messenger window states (open/closed), set custom fields, and control the visibility of the chat launcher button.

• Methods: Manage the chat experience dynamically by controlling the message editor, resetting chat sessions, adding custom options/settings, handling popup visibility, and showing or hiding the widget as needed.

• Event Listeners: Respond to user interactions, such as form validation and actions within the “More Options” menu, to create a seamless chat experience.

Properties

To configure the chat widget, use the window['boldChatSettings'] object. Place this script above your embedded code and adjust the properties as needed:

window['boldChatSettings'] = {
    email: "",
    name: "",
    phoneNo: "",
    maintainIsOpen: true,
    isLauncherVisible: true,
    fields: {
        fieldAPIName: "",
    },
    storageStrategy: "local",
};

Pre-fill Visitor Details

You can pre-fill user details before initializing the chat. This improves the user experience by eliminating the need for manual entry.

Custom Field Values (fields)

The fields property allows you to pre-fill custom chat fields. Ensure you use the correct Field API Name to store these details properly.

window['boldChatSettings'] = { 
    fields: { 
        // If the field is a text box
        cf_subscriptionType: "Premium", 
        
        // If the field is a dropdown (pass the option ID)
        cf_control: "546", 
        
        // If the field is a multi-select dropdown (pass an array of option IDs)
        cf_framework: ["552", "553"], 
        
        // If the field is a radio button (pass the value as string)
        cf_resolved: "false"
    }
};

To find the Field API Name, navigate to:
Admin → Chat → Fields → Chat Fields

Persist Chat Window State (maintainIsOpen)

This setting determines whether the chat window remains open across different browser tabs and reloads.

• true (default): The chat window state persists across tabs and page reloads.
• false: Each tab operates independently and resets upon page reload.

window['boldChatSettings'] = { maintainIsOpen: false };

Control Launcher Visibility (isLauncherVisible)

This setting controls the visibility of the chat launcher button.

• true (default): The chat launcher button is visible.
• false: The launcher button is hidden.

window['boldChatSettings'] = { isLauncherVisible: false };

Storage Strategy (storageStrategy)

This setting controls how the chat session data is stored across page reloads and browser tabs.

• cookie (default): Session data is stored using cookies. This allows basic session persistence but may have limitations across tabs or based on cookie policies.

• local: Session data is stored using localStorage, which allows persistence across page reloads and browser tabs.

window['boldChatSettings'] = { storageStrategy: 'local' };

Methods

The following methods allow dynamic control over the chat widget.

Initializing $boldChat

Before using any chat widget methods, ensure that $boldChat is properly initialized as an array:

window.$boldChat = window.$boldChat || [];

Enable/Disable Message Sending (set:canSend)

Controls whether users can send messages by toggling the visibility of the text input field.

window.$boldChat.push(["set:canSend", false]); // Disable message sending
window.$boldChat.push(["set:canSend", true]);  // Enable message sending

Reset Chat Session (do:clearSession)

Resets the chat session by clearing messages, cookies, and local storage. Learn more

window.$boldChat.push(["do:clearSession"]);

Add Custom Options (do:addOption)

Adds new options/settings to the chat widget dynamically with displayed on top right corner. Learn more

window.$boldChat.push(["do:addOption", "Clear Session"]);

Open/Close Messenger Popup (do:setIsOpen)

Controls whether the chat messenger popup is open or closed.

window.$boldChat.push(["do:setIsOpen", true]);  // Open the chat messenger popup
window.$boldChat.push(["do:setIsOpen", false]); // Close the chat messenger popup

Show/Hide Entire Widget (do:setIsVisible)

Controls the visibility of the entire chat widget, including the launcher and messenger.

window.$boldChat.push(["do:setIsVisible", true]);  // Show the chat widget
window.$boldChat.push(["do:setIsVisible", false]); // Hide the chat widget

Event Listeners

You can use the following event listeners to handle specific user interactions within the chat widget:

• validateForm – Handles form validation before starting a conversation.
• moreOptionClick – Handles interactions with the “More Options” menu.

Before using these event listeners, ensure that $boldChat is properly initialized:

window.$boldChat = [] | window.$boldChat; 

Form Validation (on:ValidateForm)

This event listener is used for form validation before allowing a user to start a conversation.

1. Register the event listener:

window.$boldChat.push(["on:validateForm", onValidate]); 

2. Define the validation function: The function should return a Promise resolving to an object that indicates whether the form is valid.

<script type="text/javascript" >
   window.$boldChat = window.$boldChat || [];
   window.$boldChat.push(["on:validateForm", onValidate]);

   function onValidate(formData) {
       return new Promise((resolve) => {
           var response = { isValid: false, confirmationMessage: "User is not a valid user." };
           resolve(response);
       });
   }
 </script> 

3. The function should return an object in the following format:

{ 
   isValid: boolean, 
   confirmationMessage: string
} 

• If isValid is true, a conversation will be created, and the confirmationMessage will be posted on behalf of the agent. If empty, the system will use the default admin-configured message.
• If isValid is false, no conversation will be created, and the confirmationMessage will be shown in the chat to alert the user reg invalid form submission.

Handle “More Options” Clicks (on:moreOptionClick)

Triggers specific actions when a user selects an option from the “More Options” menu.

1. Register the event listener:

window.$boldChat.push(["on:moreOptionClick", onMoreOptionClick]); 

2. Define the function to handle user actions: You can define custom logic to handle each selection and execute specific tasks accordingly.

<script type="text/javascript" >
   window.$boldChat = window.$boldChat || [];
   window.$boldChat.push(["on:moreOptionClick", onMoreOptionClick]);

   function onMoreOptionClick(item) {
       if(item.name === "Clear Session") {
           window.$boldChat.push(["do:clearSession"]);
       }
   }
</script> 

This JavaScript API allows seamless customization of the Live Chat Widget by enabling developers to manage user data, control widget behavior, and respond to user interactions dynamically.

See also

• How to Handle the Bold Chat Widget Launcher with an External Button
• Add a Custom Option in the More Options Menu of the Live Chat Widget