There's a new version of the HubSpot API

Check out the new API
View Beta Docs

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

Using widget events

Last updated January 7, 2025

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

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
Example Usage: Listen for the start of a conversation: window.HubSpotConversations.on('conversationStarted', payload => { console.log( `Started conversation with id ${payload.conversation.conversationId}` ); }); Listen for the conversation window to be closed: window.HubSpotConversations.on('conversationClosed', payload => { console.log( `Conversation with id ${ payload.conversation.conversationId } has been closed!` ); }); Listen for a change in the unread count: window.HubSpotConversations.on('unreadConversationCountChanged', payload => { console.log(`New unread count is ${payload.unreadCount}!`); });