JavaScript API

The Engagement Widget JavaScript API allows JavaScript code running on your site or app to interact with the Engagement Widget. The table below lists the API methods that are available on it. These JavaScript API is accessible through the window.EngagementWidget.api object:

Method	Description	Parameters	Return Type
getTools	Gets the list of active tools in the Widget	None	Array<ToolEntry>
hideWidget	Hides the widget container	None
showWidget	Unhides the widget container	None
openWidget	Opens the widget panel	None
closeWidget	Closes the widget panel	None
toggleWidget	Opens or closes the widget panel depending on whether it is closed or open	None
showWelcomeMessages	Displays triggered welcome messages	None
hideWelcomeMessages	Hide triggered welcome messages	None
openWelcomeMessage	Triggers a specific welcome message	messageId: string
openTool	Displays a specific tool in the panel	toolId: string

---

Type Definitions

type ToolEntry = {
    /**
     * Tool id
     *
     * @readonly
     * @type {string}
     */
    readonly id: string;

    /**
     * Tool type
     *
     * @readonly
     * @type {ToolType}
     */
    readonly type: ToolType;

    /**
     * Tool display name
     *
     * @readonly
     * @type {string}
     */
    readonly title: string;

    /**
     * Indicates if this is the only tool of this type that may exist
     *
     * @readonly
     * @type {boolean}
     */
    readonly isSingleton: boolean;
};

/**
 * Types of engagement tools:
 * - Live Chat ('tool-livechat')
 * - Knowledge Library ('tool-knowledge-library')
 * - Booking Calendar ('tool-booking-calendars')
 * - Link Launcher ('tool-link-launcher')
 * - Form/Survey ('tool-form-survey')
 * - Webchat ('tool-webchat')
 * - Reviews ('tool-reviews')
 * - Extendly for HighLevel ('tool-support-chat')
 * - TawkTo Livechat ('tool-tawkto')
 * - Video Showcase ('tool-video-showcase')
 * - Dedicated iFrame ('tool-dedicated-iframe')
 * - Custom HTML ('tool-html')
 * - Rich Content ('tool-rich-content')
 *
 * @export
 * @typedef {ToolType}
 */
type ToolType =
    | 'tool-livechat'
    | 'tool-knowledge-library'
    | 'tool-booking-calendars'
    | 'tool-link-launcher'
    | 'tool-form-survey'
    | 'tool-webchat'
    | 'tool-reviews'
    | 'tool-support-chat'
    | 'tool-tawkto'
    | 'tool-video-showcase'
    | 'tool-dedicated-iframe'
    | 'tool-html'
    | 'tool-rich-content';

---

JavaScript API Examples

This section will show you a few ways you can use the Engagement Widget's JavaScript API to go beyond what's possible with the Widget Builder in ChatHQ Portal.

While these cover common scenarios, this page is far from an exhaustive list. If you feel like we're missing something feel free to add a Feature Request in our Ideas Board at https://ideas.chathq.io

Completely hide the Engagement Widget

This call will hide the main Widget panel containing the list of Enagement Tools, the Floating Action Button, and all Welcome Messages

window.EngagementWidget.api.hideWidget()

Show the Engagement Widget again after it's been hidden

This call will restore the visibility of the main Widget panel containing the list of Enagement Tools, the Floating Action Button, and Welcome Messages to the state they would be if hideWidget() had not been called.

window.EngagementWidget.api.showWidget()

Open the main Engagement Widget panel

This call will make the main widget panel, containing the list of Engagement Tools, visible. It will also hide the active Welcome Message, if one is visible.

window.EngagementWidget.api.openWidget()

Close the main Engagement Widget panel

This call will make the main widget panel, containing the list of Engagement Tools, invisible. If there is a an Welcome Message it will be made visible. Reasons a Welcome Message may be active include:

• The Welcome Message is configured to show on page load and it hasn't been dismissed by the visitor

• The Welcome Message is configured to show on scroll, the visitor scrolled the configured percentage down the page and has not dimissed the Welcome Message

• The Welcome Message is configured to show after a specified number of seconds on the page that have elapsed and the visitor has not dimissed the Welcome Message

• The Welcome Message is configured to show when an element enters the viewport of the browser, the element is currently in view, and the visitor has not dimissed the Welcome Message

window.EngagementWidget.api.closeWidget()

Toggle visibility of the main Engagement Widget panel

This call will close the main Engagement Widget panel if it is currently open (equivalent to calling closeWidget()), and will open it if it is closed (equivalent to calling openWidget()).

window.EngagementWidget.api.toggleWidget()

Hide all Welcome Messages

This call will make Welcome Messages invisible, regardless of their configured triggering behaviors.

window.EngagementWidget.api.hideWelcomeMessages()

Show Welcome Messages visible again

This call will make Welcome Messages visible again after a previous call to hideWelcomeMessages(). Note that Welcome Messages triggering (e.g: scrolling, or time on page) configuration will still determine which Welcome Message is actually diaplayed

window.EngagementWidget.api.showWelcomeMessages()