visitor-identification

Requires the conversations command group from hub-cli PR #251. hubspot conversations visitor-identification --help is authoritative.

What visitor identification is

When a known contact (someone whose email you have) visits your website, the HubSpot Conversations chat widget can identify them — linking the live chat session to their CRM record. To do this, your server generates a short-lived signed token and passes it to the HubSpot Conversations JavaScript SDK. The SDK sends the token to HubSpot, which verifies it and associates the chat session with the contact.

The token is NOT a general authentication credential. It identifies one visitor for one chat session and is useless outside the Conversations SDK.

Requirements

Requirement	Detail
Account tier	Professional or Enterprise
Required scope	conversations.visitor_identification.tokens.create
Token lifetime	12 hours; cache across page loads and refresh at least every 12 hours
Generation side	Server-side only — never generate in browser JavaScript; your private app token must remain secret

Generate a token

# Minimal — email only
hubspot conversations visitor-identification create-token \
  --email [email protected]

# With name (populates the contact preview in the widget)
hubspot conversations visitor-identification create-token \
  --email [email protected] \
  --first-name Jane \
  --last-name Doe

Output:

{"ok":true,"data":{"token":"eyJhbGciOiJIUzI1NiJ9..."}}

If the private app token is missing the required scope the CLI returns a 403 with a scope hint:

{"ok":false,"error":{"status":403,"message":"Missing scope: conversations.visitor_identification.tokens.create"}}

Setting up the private app token

The conversations.visitor_identification.tokens.create scope must be granted on the HubSpot private app whose token is in HUBSPOT_ACCESS_TOKEN. To add the scope:

1. In HubSpot: Settings → Integrations → Private Apps → [your app] → Scopes
2. Under "CRM", enable conversations.visitor_identification.tokens.create
3. Rotate the token if required after scope change