My Profile
Sign Out
Tickets
Knowledge Base
Login
Articles in this section
  2. AI Agent Builder

Bold Agent Chat Widget JavaScript API Guide

Published:

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

Setting Input Value (set:inputValue)

This setting allows you to prefill the chat input box with a predefined message.

window.$boldAgent.push(["set:inputValue", "Hello! I need help with pricing."]);

Sending a Message (do:sendMessage)

This setting allows you to send a message directly into the chat conversation.

window.$boldAgent.push(["do:sendMessage", "Hello! I want to know about pricing."]);

Setting Widget Theme (set:setTheme)

This setting allows you to switch the chat widget theme dynamically.

Light Theme

window.$boldAgent.push(["set:setTheme", "light"]);

Dark Theme

window.$boldAgent.push(["set:setTheme", "dark"]);

Complete Integration Example

Below is a full working example demonstrating all the JavaScript API commands. You can use this as a reference to implement the Bold Agent chat widget with complete programmatic control.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Bold Agent Widget</title>
  </head>
  <body>
    <h1>Bold Agent Widget Demo</h1>
    <button onclick="openWidget()">Open Widget</button>
    <button onclick="closeWidget()">Close Widget</button>
    <button onclick="showWidget()">Show Widget</button>
    <button onclick="hideWidget()">Hide Widget</button>
    <br>
    <br>
    <button onclick="clearConversation()">Clear Session</button>
    <button onclick="addOption()">Add Option</button>
    <br>
    <br>
    <button onclick="showMessageInput()">Show Message Input</button>
    <button onclick="hideMessageInput()">Hide Message Input</button>
    <br>
    <br>
    <button onclick="setInputValue()">Set Input Value</button>
    <button onclick="sendMessage()">Send Message</button>
    <button onclick="switchTheme()" id="themeSwitchBtn">Switch Theme</button>

    <!-- Replace {WIDGET-ID} with your actual widget ID -->
    <script src="https://yourdomain.com/widgetscript-api/v1/widgets/{WIDGET-ID}" defer async></script>
    
    <script type="text/javascript">
      // Initialize $boldAgent as an empty array if not already defined
      window.$boldAgent = window.$boldAgent || [];
      
      // Opens the chat widget (sets `isOpen` to true)
      function openWidget() {
        window.$boldAgent.push(["do:setIsOpen", true]);
      }
      
      // Closes the chat widget (sets `isOpen` to false)
      function closeWidget() {
        window.$boldAgent.push(["do:setIsOpen", false]);
      }
      
      // Shows the widget on screen (sets `isVisible` true)
      function showWidget() {
        window.$boldAgent.push(["do:setIsVisible", true]);
      }
      
      // Hides the widget from view (sets `isVisible` false)
      function hideWidget() {
        window.$boldAgent.push(["do:setIsVisible", false]);
      }
      
      // Clears the current chat session and conversation
      function clearConversation() {
        window.$boldAgent.push(["do:clearSession"]);
      }
      
      // Adds a custom menu option to the widget (e.g., "Clear Session")
      function addOption() {
        window.$boldAgent.push(["do:addOption", "Clear Session", "ba-icon-x-close"]);
      }
      
      // Register handler for custom option clicks from the widget
      window.$boldAgent.push(["on:moreOptionClick", onMoreOptionClick]);
      
      // Handles clicks on widget "more" options (clears session if selected)
      function onMoreOptionClick(item) {
        if (item.name === "Clear Session") {
          window.$boldAgent.push(["do:clearSession"]);
        }
      }
      
      // Enables the message input so users can type
      function showMessageInput() {
        window.$boldAgent.push(["set:canSend", true]);
      }
      
      // Disables the message input to prevent sending
      function hideMessageInput() {
        window.$boldAgent.push(["set:canSend", false]);
      }
      
      // Sets the widget's input value programmatically
      function setInputValue() {
        window.$boldAgent.push(["set:inputValue", "Hello! I need help with pricing."]);
      }
      
      // Sends a message into the widget programmatically
      function sendMessage() {
        window.$boldAgent.push(["do:sendMessage", "Hello! I want to know about pricing."]);
      }
      
      // Tracks the current theme; default is 'light'
      let currentTheme = 'light';

      // Switches between light and dark themes
      function switchTheme() {
        currentTheme = (currentTheme === 'light') ? 'dark' : 'light';
        window.$boldAgent.push(["set:setTheme", currentTheme]);
      }
    </script>
  </body>
</html>
Attachments
Access denied
Access denied