Bold Agent Chat Widget JavaScript API Guide

The Bold Agent Chat Widget offers a flexible JavaScript API that enables you to configure, extend, and automate your chat experience directly from the client side. Using this API, you can adjust widget behavior, manage chat sessions, customize actions, and respond to widget events for a seamless support experience.

The widget processes all commands pushed into the global queue window.$boldAgent. This allows interactions to be registered even before the widget is fully initialized.

Deploying the Widget on Your Website

Before using any JavaScript API commands, embed the widget into your site by placing the installation snippet in your HTML—ideally just before the closing tag. This loads the published agent and makes programmatic interactions available.

Generic Script Format

<!-- Chat Widget Embed Script -->
https://yourdomain.com/widgetscript-api/v1/widgets/{WIDGET-ID}

Initializing the Command Queue

This initializes the global command queue so API calls can be pushed immediately. It ensures commands are not lost even if the widget script finishes loading later.

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

Opening or Closing the Widget (do:setIsOpen)

This setting controls whether the chat widget is open or closed.

window.$boldAgent.push(["do:setIsOpen", true]);   // open widget
window.$boldAgent.push(["do:setIsOpen", false]);  // close widget

Showing or Hiding the Widget (do:setIsVisible)

This setting controls whether the widget is visible on the screen or fully hidden. It provides control over UI presence without removing the widget from the page.

window.$boldAgent.push(["do:setIsVisible", true]);   // show widget
window.$boldAgent.push(["do:setIsVisible", false]);  // hide widget

Clearing a Chat Session (do:clearSession)

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

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

Adding Custom Menu Options (do:addOption)

This setting adds custom controls to the widget’s More Options menu. It can be used to expose additional actions such as clearing sessions or navigating to help sections.

window.$boldAgent.push(["do:addOption", "Clear Session", "ba-icon-x-close"]);
window.$boldAgent.push(["do:addOption", "Help", "ba-icon-info"]);

Handling Menu Option Clicks (on:moreOptionClick)

This setting registers an event handler to respond when users click custom menu items. Based on the selected item, it executes predefined operations such as session clearing or navigation.

window.$boldAgent.push([
  "on:moreOptionClick",
  function(item) {
    if (item.name === "Clear Session") {
      window.$boldAgent.push(["do:clearSession"]);
    }
    if (item.name === "Help") {
      console.log("Help clicked!");
    }
  }
]);

Enabling or Disabling Message Input (set:canSend)

This setting controls whether users can type and submit messages in the chat input.

window.$boldAgent.push(["set:canSend", true]);    // enable input
window.$boldAgent.push(["set:canSend", false]);   // disable input