There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Using widget events

Last updated June 17, 2020

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

Supported events

conversationStarted - Emitted when a new conversation has been successfully started. The event payload will include a Conversations object, which will contain details about the conversation that was started. See below for details about the data in this object.

conversationClosed - Emitted when a new conversation has been successfully closed. The event payload will include a Conversations object, which will contain details about the conversation that was closed. See below for details about the data in this object. 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.

unreadConversationCountChanged - Emitted when the number of conversations in the widget with any unread messages changes (increase or decrease). The event payload will include an unreadCount field, indicating the number of conversations in the widget with any unread messages.


Registering event listeners.

Event listeners are registered using the HubSpotConversations.on() function:

window.HubSpotConversations.on('conversationStarted', payload => {
console.log(payload);
});

Event listeners can be removed by using the HubSpotConversations.off() function:

const handleEvent = eventPayload => console.log(eventPayload);

// Register an event listener
window.HubSpotConversations.on('conversationStarted', handleEvent);

/* ... */

// Remove the event listener
window.HubSpotConversations.off('conversationStarted', handleEvent);
Data types:

The conversationStarted and conversationClosed events will include a Conversations object in the payload. This object contains the following data:

Field name Data type Description
conversationId Number The id of the conversation