Visitor Identification
Marketing Hub
- Professional or Enterprise
Sales Hub
- Professional or Enterprise
Service Hub
- Professional or Enterprise
CMS Hub
- Professional or Enterprise
Please note: this API cannot be used with bots.
• Access to the Visitor Identification API requires a Professional or Enterprise level subscription. If the account does not have a qualifying subscription, you will receive a 403 error response from the API.
Example Integration Flow

1. On your front end, set loadImmediately
to false on the hsConversationsSettings
object on the window. If you do not do this, the chat widget may load before the identification information is passed through.
See the Chat Widget SDK primer below for more information on the API.
Please note: You need to set the hsConversationsSettings
properties outside of the isConversationsAPIReady
function. The hsConversationsSettings
needs to be set prior to the call, otherwise you may experience a race condition that interferes with widget load.
The provided first and last name will be set after the chat beings on the contact in HubSpot if:
- It is a new contact created by the Visitor Identification API
- It is an existing contact where the name is not already known
This can be useful when personalizing messages to identified visitors when your external system already has name information, but it does not yet exist in HubSpot. These are optional parameters and not required.
3. Using the token Step 2, set the following properties on the hsConversationsSettings object on the window.
The token and email must be set on the hsConversationsSettings object on the window every time the page loads for an authenticated visitor. This context will not be carried across page loads automatically if these parameters are no longer set. Tokens are temporary and will expire after 12 hours. Tokens can be cached to avoid re-fetching the token on every page load, as long as they are refreshed at least every 12 hours.
Verifying the Integration

Chat Widget SDK Primer
Getting started
SDK Reference
Field name
|
Data type
|
Default
|
Description
|
loadImmediately
|
boolean
|
true
|
Whether the widget should implicitly load or wait until the widget.load method is called
|
identificationToken
|
string
|
“”
|
Used to integrate with the Visitor Identification API. This is the token provided by the token generation endpoint on the Visitor Identification API that is used as proof that this visitor has been identified.
|
identificationEmail
|
string
|
“”
|
The email address of the visitor that you’ve identified as loading the widget.
|
Thank you for your feedback, it means a lot to us.