Last modified: August 22, 2025
Use the visitor identification API to identify visitors to your site that were authenticated using your own external authentication system. An identification token returned from this API can be used to pass information about your already-authenticated visitor to the chat widget, so that it treats the visitor as a known contact. Agents in the inbox can then have confidence about who they are talking to, and visitors can access previous thread history across devices. For example, if you host your own web app behind a login, you may set up the HubSpot chat widget to appear on pages within your web app where you know that visitors have already been authenticated and identified. Currently, any visitor chatting in on those pages would still show up as “Unknown visitor” in the Conversations inbox, despite being an identified, logged-in visitor in your web app. Using the Visitor Identification API, you can pass authenticated visitor information directly to the chat widget, which identifies them in the Conversations inbox.

​
Please note:

  • The visitor identification API is for telling HubSpot who the visitor is. You should not rely on this to authenticate users in your platform.
  • 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

To integrate with this feature, you must have an existing web application with an authentication system. Before getting started, make sure you have a private appset up and the account that you are trying to integrate has a qualifying Professional or Enterprise subscription. Here’s an example of a possible integration flow:
Possible User Identification Flow
Once your customer is logged in and verified in your system, take the following steps to identify them within live chat: 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.
  • Set the hsConversationsSettings properties outside the isConversationsAPIReady function.
  • In addition, the hsConversationsSettings needs to be set prior to the call, otherwise you may experience a race condition that interferes with widget load.
window.hsConversationsSettings = {
  loadImmediately: false,
};
2. Generate a token from the Visitor Identification API by passing in the email address of your authenticated visitor. This should be done on the back end of your web application. Check out the endpoints reference documentation for an example request. 
curl --request POST \
  --url 'https://api.hubspot.com/conversations/v3/visitor-identification/tokens/create \
--data '{
  "email": "gob@bluth.com",
  "firstName": "Gob",
  "lastName": "Bluth"
}'
The provided first and last name will be set on the contact record in HubSpot after the chat begins if:
  • It’s a new contact created by the Visitor Identification API.
  • It’s 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. 
window.hsConversationsSettings = {
  identificationEmail: 'visitor-email@example.com',
  identificationToken: '<TOKEN FROM STEP 1>',
};
4. Load the widget. 
window.HubSpotConversations.widget.load();
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.

​
Verify the integration

Once you’ve completed your integration of the Visitor Identification feature, you can verify that it’s working as expected. This can be done in a couple ways, depending on your implementation, so you may need to tailor the examples below to your specific requirements.
  • If you’ve added the chat widget to one or more public pages as well as behind an authentication system:
    • Navigate to a page where the chat widget should not be identifying visitors and start a conversation.
    • In HubSpot, open the inbox and verify that the chat that just came in belongs to an Unknown Visitor. If this is not the case, try following these steps in a private browsing window:
      • Navigate to a page where the chat widget should be identifying visitors via the Visitor Identification API and start a conversation.
      • In HubSpot, open the inbox and verify that the chat is correctly attributed to the contact that you’re logged in as. You should see a badge next to the contact’s name, indicating that this contact was successfully identified through this API.
visitor_identity_badge
  • If you’ve only added the chat widget to pages behind an authentication system, and you have access to multiple test user accounts:
    • Log in to HubSpot as the first test user, then navigate to a page where the chat widget loads, and start a conversation.
    • Log out of HubSpot, then log back in as the second test user. Navigate to a page where the chat widget loads, and start a conversation.
    • In HubSpot, open the inbox and verify that the chats that came in were from the first and second test accounts, respectively, and that you see the badge next to the contact names for both records.

​
Please note:

For visitors identified with this API, HubSpot will not drop the messagesUtk cookie. HubSpot will also skip any email capture questions since email address is already known. Because the messagesUtk cookie and email capture do not apply to these chats, the associated settings in the chatflow will not show for visitors identified through the Visitor Identification API.

​
Chat widget SDK primer

The API is housed in the window.HubSpotConversations object. 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’s initialized, you may use the window.hsConversationsOnReady helper. For example: 
<script type="text/javascript">
  function onConversationsAPIReady() {
    console.log(`HubSpot Conversations API: ${window.HubSpotConversations}`);
  }
  /*
    configure window.hsConversationsSettings if needed.
  */
  window.hsConversationsSettings = {};
  /*
   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>

​
SDK reference

window.hsConversationsOnReady array This is an optional field you can define on the window object that enables you to specify code to be executed as soon as the widget becomes available. Once the API has been initialized, it will check for the existence of this array and execute its functions in series. 
if (window.HubSpotConversations) {
  console.log('The api is ready already');
} else {
  window.hsConversationsOnReady = [
    () => {
      console.log('Now the api is ready');
    },
  ];
}
hsConversationsSettings object This object enables you to provide some configuration options to the widget before it initializes. In order to use the Visitor Identification feature, you must set the following fields:
ParameterTypeDescriptionDefault
loadImmediatelybooleanWhether the widget should implicitly load or wait until the widget.load method is calledtrue
identificationTokenstringUsed 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.""
identificationEmailstringThe email address of the visitor that you’ve identified as loading the widget.""
window.hsConversationsSettings = {
  loadImmediately: false,
  identificationEmail: 'visitor-email@example.com',
  identificationToken: '<TOKEN FROM STEP 1>',
};
Learn more about the conversations SDK.