This guide provides an overview of the BoldDesk Live Chat Web SDK package, built to simplify the integration and management of the BoldDesk Live Chat Widget. This SDK enables you to embed the widget into your website, pre-fill visitor details, set localisation options, and dynamically control widget behaviour.

Fully compatible with frameworks like React, Vue, and Angular, it offers a robust wrapper around $boldChat methods, enhanced with TypeScript definitions for a seamless development experience.

In this guide, you will learn about:

• Installation: How to install and add the SDK to your project.
• Configuration Options: Load the widget and set options like email and locale.
• Methods & Event Listeners: Interact with the widget programmatically using available methods and event hooks.

What You Can Do With the SDK

• Embed the BoldDesk Live Chat Widget using WIDGET_ID and BRAND_URL
• Pre-fill visitor email before chat creation
• Set widget localisation via locale codes
• Programmatically control widget visibility and conversation state
• Add custom items to the widget “More Options” menu and respond to user clicks
• Validate widget form input before a conversation is created

Installation

To install the SDK in your project, run the following command:

npm install @bolddesk/live-chat-web-sdk

Configuration Options

1. Create a Live Chat Widget

If you haven’t created a widget yet, explore further instructions about How to Set Up a Live Chat Widget in BoldDesk.

2. Configure the Widget in Code

Import and configure the widget in your codebase. Once set up, the widget automatically appears and allows visitors to chat.

  import { LiveChat } from '@bolddesk/live-chat-web-sdk';
  LiveChat.configure(WIDGET_ID, BRAND_URL);   

Get Your WIDGET_ID and BRAND_URL

1. Go to Admin > Chat > Live Chat in the agent portal and select your widget.
   
   

   
   
   

2. Navigate to Installation > NPM Package to find the configuration snippet.
   

   
   
   

Optional Configuration

Pre-fill Email

Pre-fills the visitor’s email. If provided, visitors don’t need to enter it manually. The conversation is created using this email once the visitor sends their first message.

LiveChat.configure(WIDGET_ID, BRAND_URL, { email: "[email protected]" }); 

Set Language

In order to load the live chat widget in a specific language, set the language code in the configure method.

Example for French:

LiveChat.configure(WIDGET_ID, BRAND_URL, { locale: "fr" }) // French
LiveChat.configure(WIDGET_ID, BRAND_URL, { locale: "ja" }) // Japanese

Methods and Event Listeners

Use the methods and events below to dynamically control and interact with the live chat widget.

Widget Visibility & Control

Add Custom Option to “More Options” Menu

LiveChat.addMoreOptions('Clear Session');

Form Validation (onValidateForm)

Use this to validate the visitor’s email before allowing them to start a conversation.

Register the Validation Handler

LiveChat.onValidateForm(this.onValidate); 

Define the Validation Logic

Define the validation function: The function should return an object that indicates whether the form is valid.

private onValidate(formData: { apiName: string; value: string; }[]) {
  if (formData[0].value === '[email protected]') {
    return { isValid: false, confirmationMessage: 'Email is not valid' };
  } else {
    return { isValid: true, confirmationMessage: 'Email is valid' };
  }
}

The function should return an object in the following format (confirmation message is optional):

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

Handle “More Options” Menu Clicks (onMoreOptionClick)

Registers a callback for custom operations when a user selects an option from the “More Options” menu.

Register the Handler

LiveChat.onMoreOptionClick(this.handleMoreOptionClick); 

Define Custom Logic

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

private handleMoreOptionClick(item: { name: string }): void {
    if (item.name === 'Clear Session') {
      LiveChat.clearConversation();
    }
}

Frequently Asked Questions

1. Where do I get the widget installation snippet?
   Go to Admin > Chat > Live Chat, open the widget, then go to Installation (including NPM Package) to copy the snippet values.

2. Can the widget load in different languages?
   Yes. Set locale in LiveChat.configure. The widget supports languages enabled in Customer Portal → Languages.
   Related: Enhancing Live Chat with Multilingual Support

3. Can I pre-fill the visitor email so the visitor does not type it?
   Yes. Pass { email: "[email protected]" } in LiveChat.configure. The email is used when the visitor sends the first message.

4. Can I block conversation creation for invalid email addresses?
   Yes. Register LiveChat.onValidateForm(...) and return { isValid: false, confirmationMessage: "..." } to prevent conversation creation.

5. Can I programmatically hide the widget or disable the message input?
   Yes. Use LiveChat.hideWidget() / LiveChat.showWidget() and LiveChat.hideMsgInput() / LiveChat.showMsgInput().

6. How do I clear a visitor’s session?
   Use LiveChat.clearConversation() to clear the session (messages, cookies, storage). You can expose this via a custom “More Options” item using LiveChat.addMoreOptions(...).

Related Articles

1. Enhancing Live Chat with Multilingual Support
2. How to Set Up a Live Chat Widget in BoldDesk
3. How to configure and integrate Mobile Chat SDK in iOS App
4. How to configure and integrate Mobile Chat SDK in Android App