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 chat fields and custom ticket fields, control the chat messenger popup maximized state 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: "",
    },
    ticketFields: {
        fieldAPIName: "",
    },
    storageStrategy: "local",
    isWidgetMaximized: false,
};

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 Chat 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: { 
        
        cf_subscriptionType: "Premium", // If the field is a text box 
       
        cf_control: "546",  // If the field is a dropdown (pass the option ID)
        
        cf_framework: ["552", "553"], // If the field is a multi-select dropdown (pass an array of option IDs)
        
        cf_resolved: "false"   // If the field is a radio button (pass the value as string)
    }
};

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

Custom Ticket Field Values (ticketFields)

The ticektFields property allows you to pre-fill custom ticket fields in the offline custom form. Ensure you use the correct Field API Name to store these details properly.

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

To find the Field API Name, navigate to:
Admin → Help Desk → Fields and Forms → Ticket Fields

The prefilled values in the custom ticket fields are displayed as shown in the image below.

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.

• none: No session data is stored. Each page reload starts a new session, and previous chat history is not retained.

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

Control Chat Messenger Popup Maximized State (isWidgetMaximized)

This setting controls the maximized state of the chat messenger popup.

• false (default): The chat messenger popup appears in a minimized state.
• true: The chat messenger popup appears in a maximized state.

window['boldChatSettings'] = { isWidgetMaximized: true };

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