Visitor Identification

OverviewEndpoint
APPLICABLE PRODUCTS
  • Marketing Hub
    • Professional or Enterprise
  • Sales Hub
    • Professional or Enterprise
  • Service Hub
    • Professional or Enterprise
  • CMS Hub
    • Professional or Enterprise
 
The Visitor Identification API allows you to identify visitors to your site that were authenticated using your own external authentication system. This API currently works in conjunction with HubSpot’s live chat tool. 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.
Example Use Case:
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

In order to integrate with this feature, you must have an existing web application with an authentication system.
 
Before we begin, make sure you have an api key set up and the portal that you are trying to integrate has a qualifying pro 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 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.

JavaScript 
window.hsConversationsSettings = {
  loadImmediately: false
};
2. Generate a token from the Visitor Identification API (see the Endpoints tab for an example request), by passing in the email address of your authenticated visitor. This should be done on the back end of your web application. 
 
Please note: For security reasons, you should not expose your HubSpot API key on the front end.
Shell script 
curl --request POST \
  --url 'https://api.hubspot.com/conversations/v3/visitor-identification/tokens/create?hapikey=YOUR_HUBSPOT_API_KEY' \
--data '{
  "email": "gob@bluth.com",
  "firstName": "Gob",
  "lastName": "Bluth"
}'

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.

JavaScript 
window.hsConversationsSettings = {
   identificationEmail: "visitor-email@example.com",
   identificationToken: "<TOKEN FROM STEP 1>"
};
4. Load the widget. 
JavaScript 
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. 

Verifying the Integration

Once you have completed your integration of the Visitor Identification feature, you will want to verify that it’s working as expected.
 
Below we have outlined a couple of flows that you could test depending on the setup of your specific application. We have outlined a few main use cases, but you may need to tailor them for your exact use case.
 
If you have the chat widget on one or more public pages as well as behind an authentication system:
 
First, navigate to a page where the chat widget should not be identifying visitors and start a conversation. Go into the inbox in your HubSpot portal 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 an Incognito or private browsing window.
 
Second, navigate to a page where the chat widget should be identifying visitors via the Visitor Identification API and start a conversation. Then, go into the Inbox in your HubSpot portal 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 only have the chat widget load on pages behind an authentication system, and you have access to multiple test user accounts:
 
Log in as the first test user, navigate to a page where the chat widget loads, and start a conversation. Log out, and log back in as the second test user. Navigate to a page where the chat widget loads, and start a conversation. Then, go into the inbox in your HubSpot portal 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

Getting started

 
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. See below for a simple example:
HTML 
<script type="text/javascript">
  function onConversationsAPIReady() {
    console.log(`HubSpot Conversations API: ${window.HubSpotConversations}`);
  }

  /*
   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
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.
JavaScript 
if (window.HubSpotConversations) {
  console.log('The api is ready already');
} else {
  window.hsConversationsOnReady = [
    () => {
      console.log('Now the api is ready');
    },
  ];
}
hsConversationsSettings
 
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:
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.
JavaScript 
window.hsConversationsSettings = {
  loadImmediately: false,
   identificationEmail: "visitor-email@example.com",
   identificationToken: "<TOKEN FROM STEP 1>"
};
For more information on how the Chat Widget SDK works, check out these docs.