BoldDesk Live Chat Widget JavaScript API Guide

The BoldDesk Live Chat Widget provides a powerful JavaScript API that allows you to configure, extend, and automate your chat experience directly from the client side. This guide explains how to define visitor details, configure widget behavior, interact with chat fields and ticket fields, manage the widget programmatically, and respond to key lifecycle events.

Introduction to the JavaScript API

The JavaScript API is designed to help teams tailor the Live Chat Widget to their environment. Using a combination of configuration properties, runtime methods, and event listeners, you can prefill visitor information, manage chat sessions, customize interface behavior, and implement advanced workflows such as validation, dynamic UI updates, and analytics.
Every customization begins by defining the boldChatSettings object and initializing the $boldChat command queue.

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.

Configuring Widget Behavior with boldChatSettings

Place your configuration script above the embedded widget code. These settings determine the widget’s display behavior, prefilled values, form handling, and session persistence.

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

Prefilling Visitor Details

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

Setting Chat Field Values

The fields configuration block allows you to prefill Custom Chat Fields using their Field API Names.

Examples:

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

Populating Ticket Fields on the Offline Form

Use the ticketFields block to prefill Custom Ticket Fields shown when the offline contact form appears.

This applies only when the offline form type is set to Contact Form with ticket fields.

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.

Persistence and Visibility Controls

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

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

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

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

Managing the Widget with $boldChat Methods

The following methods allow dynamic control over the chat widget.
Before using any chat widget methods, ensure that $boldChat is properly initialized as an array:

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

Controlling Message Input (set:canSend)

Enable or disable the visitor’s ability to send messages:

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

Clearing a Chat Session (do:clearSession)

Resets the chat session by clearing messages, cookies, and local storage. Explore further instructions about Add a Custom Option in the More Options Menu of the Live Chat Widget.

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

Adding Custom Menu Options (do:addOption)

Add custom actions, displayed in the widget’s “More Options” menu. Learn more about Add a Custom Option in the More Options Menu of the Live Chat Widget.

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

Opening and Closing the Messenger (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

Showing or Hiding the 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 for Dynamic Interaction

The Live Chat Widget provides a flexible event system that enables real‑time validation, custom UI behaviors, internal workflows, and conversation tracking.
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.
• beforeEmailSubmit - Handles email submission before starting a conversation and on workflow email submit.
• conversationStarted - Fired when a new chat conversation is successfully created and initiated.
• conversationClosed - Fired when the active chat conversation is closed by either the customer or the agent.

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

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

Validating Forms Before Conversation Creation (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 regarding invalid form submission.

Handling Custom Option 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.

Email Validation Before Submission (on:beforeEmailSubmit)

Triggers specific actions when a user enters an email in the pre-chat form or submits email via workflow.

1. Register the event listener:

window.$boldChat.push(["on:beforeEmailSubmit", onBeforeEmailSubmit]); 

2. Define the before email submit function; this function will be triggered and executed when an email is submitted in the pre-chat form or via workflow.

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

    async function onBeforeEmailSubmit(email) {
        console.log("Submitted Email: ", email);
        var isValid = // write your code to validate email.
        var response = { isValid: isValid, confirmationMessage: "The given email is not a business mail."}
        return response;
    }
</script> 

3. If required, the function may return an object in the following format:

{ 
    isValid: boolean, 
    confirmationMessage: string
} 

• If isValid is true, a conversation will be created.
• If isValid is false, conversation will not be created, and the confirmationMessage will be shown in the error notification message.
• If the function does not return an object, the existing flow continues and conversation is created as usual.

Tracking Conversation Start (on:conversationStarted)

This event fires when BoldDesk successfully creates a conversation.

window.$boldChat.push(["on:conversationStarted", async (context) => {
 // Update in-page indicators, start analytics timers, etc.
}]); 

Useful for analytics, routing feedback, or UI effects.

Tracking Conversation Closure (on:conversationClosed)

Triggered when the visitor or agent closes a conversation:

window.$boldChat.push(["on:conversationClosed", async (context) => {
 // Reset UI, update counters, finalize logs
}]); 

Ideal for lifecycle management and user experience consistency.

FAQs

1. Does the widget support asynchronous validation in lifecycle events?
Yes. All major events—including on:validateForm and on:beforeEmailSubmit—support async handlers, allowing you to apply business rules before a conversation begins.

2. Is it possible to disable the message input while running checks?
Yes. Use [“set:canSend”, false] to pause message sending and re-enable it once your logic finishes.

3. How do Chat Fields differ from Ticket Fields in the widget?
Chat Fields appear within the chat workflow, while Ticket Fields populate the offline contact form. Ticket Fields require the Contact Form with ticket fields setting.

4. Can I track when conversations start and end for reporting?
Yes. Use the new on:conversationStarted and on:conversationClosed events to record timestamps, update the UI, or implement analytics logic.

5. How do I fully reset a user’s session?
Call [“do:clearSession”] manually or via a custom menu option triggered in on:moreOptionClick.

6. Can I hide the launcher but still open the chat programmatically?
Yes. Set isLauncherVisible: false and call [“do:setIsOpen”, true] when needed.

Related Articles

• 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