Ask or search…
K

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()