Conversations SDK
HubSpot's Live Chat widget allows you to chat with customers and leads on your own website. With the Chat Widget SDK, you can provide a more tailored experience for visitors by customizing the behavior of the chat widget.
Use case: The Chat Widget SDK can be used to customize when and how HubSpot's chat widget appears on your website.
At a high level, it allows you to do the following:
- Control the widget's behavior
- Listen for and respond to events in the widget
- Poll to understand widget state
Getting started
The API is housed in the window.HubSpotConversations
object. All available methods can be accessed via this object. The HubSpot script loader (aka the HubSpot tracking code) on your page will create this object for you, but it may not be available immediately. To defer accessing the API until it's initialized, you may use the window.hsConversationsOnReady
helper. See below for a simple example:
SDK Reference
window.hsConversationsOnReady
This is a special field you can define on the window
object that enables you to specify code to be executed as soon as the widget 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. For example:
hsConversationsSettings
This object enables you to provide some configuration options to the widget before it initializes. Usage of this object is optional.
Field name | Data Type | Default | Description |
---|---|---|---|
|
Boolean | true | Whether the widget should implicitly load or wait until the widget.load method 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 via widget.remove |
enableWidgetCookieBanner |
Enum | false | Control behavior of the cookie banner for all chatflows on the page:false - use the setting from chatflows (default)true - enable cookie banners when the widget is loadedON_WIDGET_LOAD - same as true: enable cookie banners when the widget is loadedON_EXIT_INTENT - enable cookie banners when the user exhibits an exit intentNote that this field used to be a Boolean . It can now accommodate both the original Boolean values and the updated enum values. |
disableAttachment |
Boolean | false | Whether or not the upload attachment button should be hidden in the chat widget. |
disableInitialInputFocus |
Boolean | false | Determines whether to automatically prevent focusing on the widget's input field after an inline embedded widget is initially loaded on a page. |
Inline embed styling
window.hsConversationsOnReady
When the widget is embedded at a customer-specified location, several DOM elements are added and can be styled to suit the customer's customization requirements (e.g. height, width, border). Note that this structure only applies if you use the inlineEmbedSelector
option.
<div id="hubspot-conversations-inline-parent">
<iframe id="hubspot-conversations-inline-iframe" />
</div>
For example, the chat widget may look like this by default:
This squashed layout isn't an ideal experience, so you can customize the widget by including styles like this:
#hubspot-conversations-inline-iframe {
width: 300px;
height: 500px;
border:none;
}
This provides a much more friendly user experience.
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 the loadImmediately
flag to false
. Otherwise, the widget will load itself automatically.
Note: widget.load
is 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 |
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 for refreshing the widget on route changes. This allows you to specify different chatflows on different page routes. If widget.refresh
is called on a route where there is no chatflow, and the user isn't engaged in a conversation, the widget will be removed.
Note: widget.refresh
is throttled to one call per second.
Parameters:
Field Name | Data Type? | Default | Description |
---|---|---|---|
openToNewThread |
Boolean | false | Whether to force a new thread to be created |
For an example of how to use the openToNewThread
field, see Opening a specific chatflow.
Example:
widget.close
Close the widget. If the widget is already closed or isn't currently loaded, this is a no-op.
Example:
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 invoke widget.load
.
Example:
clear
The chat 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.
The following cookies are cleared with this method:
messagesUtk
hs-messages-is-open
hs-messages-hide-welcome-message
For more information about these cookies, see this knowledge base article.
Example:
Additionally, you can pass {resetWidget:true}
to the clear()
function to clear all chat related cookies, remove the widget from the page, and create a new instance of the chat widget.
Example:
Event specification
The chat widget will emit various events you can listen and respond to throughout its lifecycle.
Supported events
conversationStarted
Emitted when a new conversation has been successfully started.
Event payload
Field name | Data type | Description |
---|---|---|
conversation |
Conversation | Details about the conversation that was started |
Example:
conversationClosed
Emitted when a new conversation has been successfully closed.
Note: This event fires when the conversation is marked as closed from the conversations inbox, and is unrelated to the user minimizing or closing the chat widget.
Event payload
Field name | Data type | Description |
---|---|---|
conversation |
Conversation | Details about the conversation that was closed |
Example:
unreadConversationCountChanged
Emitted when the number of conversations in the widget with any unread messages changes (increase or decrease).
Event payload
Field name | Data type | Description |
---|---|---|
unreadCount |
Number | The new total of conversations in the widget with any unread messages |
Example:
contactAssociated
Emitted when the the visitor is associated with a contact in the CRM.
Event payload
Field name | Data type | Description |
---|---|---|
message |
String | A confirmation message that the visitor has been associated with a contact |
Example:
userInteractedWithWidget
Emitted as soon as the user interacts with the widget (e.g., clicking the launcher to open the widget, closing the initial welcome message, etc.)
Event payload
Field name | Data type | Description |
---|---|---|
message |
String | A confirmation message that the user has interacted with the widget. |
Example:
widgetLoaded
Emitted when the widget iframe has loaded.
Event payload
Field name | Data type | Description |
---|---|---|
message |
String | Confirmation message that the widget iframe has loaded. |
Example:
quickReplyButtonClick
Emitted when the user clicks the quick reply button in a bot conversation
Event payload
Field name | Data type | Description |
---|---|---|
value |
Array | Contains the text content of the quick reply button that was clicked. |
Example:

In the example screenshot above, the bot chatflow contains three quick reply options available for the user to select. If the user selected Learn more, then the resulting event payload would be:
widgetClosed
Emitted when the widget is closed.
Event payload
Field name | Data type | Description |
---|---|---|
message |
String | Confirmation message that the widget is closed. |
Example:
Thank you for your feedback, it means a lot to us.