BoldDesk Live Chat Web SDK: Integrate & Control Chat Widget

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 localization options, and dynamically control widget behavior.

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.

Installation

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

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

Configuration Options

Step 1: Create a Live Chat Widget

If you haven’t created a widget yet, follow this guide to create one.

Step 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: "example@example.com" }); 

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 === 'test@gmail.com') {
    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();
    }
}