HubSpot Conversations JavaScript API

The Conversations Live Chat widget allows you to engage in conversations directly on your website. This API is intended to give you more control over the widget so that you can provide a more tailored experience for your visitors.

Getting Started

The API is housed in thewindow.HubSpotConversationsobject. All available methods can be accessed via this object. The HubSpot script loader on your page will create this object for you, but it may not be available immediately. To defer accessing the API until it has been initialized, you may use thewindow.hsConversationsOnReadyhelper. See below for a simple example:

<scripttype="text/javascript">functiononConversationsAPIReady() {
console.log(`HubSpot Conversations API: ${window.HubSpotConversations}`);
}
/*
If external API methods are already available, use them.
*/if (window.HubSpotConversations) {
onConversationsAPIReady();
} else {
/*
Otherwise, callbacks can be added to the hsConversationsOnReady on the window object.
These callbacks will be called once the external API has been initialized.
*/window.hsConversationsOnReady = [onConversationsAPIReady];
}
</script>

API Reference

window.hsConversationsOnReady

This is a special field that you can define on thewindowobject that enables you to specify code to be executed as soon as the API becomes available. Usage of this property is optional. If used, this field should be set to an array of functions. Once the API has been initialized it will check for the existence of this array and execute its functions in series.

hsConversationsSettings

This object enables you to provide some configuration options to the api before it initializes. Usage of this object is entirely optional.

Fields

Field name

Data type

Default

Description

loadImmediately

Boolean

true

Whether the widget should implicitly load or wait until thewidget.loadmethod is called

inlineEmbedSelector

String

""

Where the widget should be embedded in the page. If a selector (e.g.#some-id) is provided, the widget will be embedded inline within that DOM node. It will always be open until it is removed viawidget.remove

HubSpotConversations.widget

The widget object contains a number of methods that allow you to manipulate the chat widget on your page.

widget.load

Load the widget for the first time on the page. If the widget is currently loaded, subsequent calls to this method are no-ops.

This method is only necessary if you set theloadImmediatelyflag tofalse. Otherwise, the widget will load itself automatically.

Note:widget.loadis throttled to one call per second

Parameters

Field name

Data type

Default

Description

widgetOpen

Boolean

false

Whether the widget should load in an open state.

Example usage:

window.HubSpotConversations.widget.load();
/* ... */// Force the widget to load in an open statewindow.HubSpotConversations.widget.load({ widgetOpen: true });

widget.refresh

Refresh and re-render the widget's information, given the current page url.

If you house the chat widget on a single-page application, this method can be useful to refresh the widget on route changes. This allows you to specify different chatflows on different page routes. Ifwidget.refreshis called on a route where there is no chatflow, and the user is not engaged in a conversation, the widget will be removed.

Note:widget.refreshis throttled to one call per second

Example usage:

window.HubSpotConversations.widget.refresh();

Note:widget.refreshwill not remove existing conversations that a page visitor has started in the widget.

widget.open

Open the widget. If the wigdet is already open, or the widget is not currently loaded, this is a no-op.

Example usage:

window.HubSpotConversations.widget.open();

widget.close

Close the widget. If the wigdet is already closed, or the widget is not currently loaded, this is a no-op.

Example usage:

window.HubSpotConversations.widget.close();

widget.remove

Remove the widget from the page. If the widget is not present on the page, this is a no-op. To display the widget again, a full page refresh will have to occur, or one can invokewidget.load.

clear

The Conversations widget creates several cookies to preserve its state across site visits and page refreshes. These cookies are scoped to the domain of the page hosting the widget, and are used to support the following features:

Referencing historical conversations

Persisting the open state of the chat widget across page loads

Persisting the open state of the welcome message across page loads

The clear method can be used to delete these cookies, returning the widget to its default state on subsequent loads.

Example usage:

window.HubSpotConversations.clear();

Event Specification

The Conversations widget will emit various events throughout its lifecycle to which you can listen and respond.