Back to Details

visitor-identification

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Requires the 
conversations
command group from hub-cli PR #251. 
hubspot conversations visitor-identification --help
is authoritative.
需要使用 hub-cli PR #251 中的 
conversations
命令组。
hubspot conversations visitor-identification --help
是权威参考。

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.
当已知联系人（即你掌握其邮箱的联系人）访问网站时，HubSpot Conversations 聊天组件可以识别该联系人，从而将实时聊天会话与其 CRM 记录关联。为此，你的服务端需要生成一个短期有效的签名 token，并将其传递给 HubSpot Conversations JavaScript SDK。SDK 会将 token 发送给 HubSpot，由 HubSpot 进行验证并将聊天会话与该联系人关联。
该 token 不是通用身份验证凭据。它仅用于在一次聊天会话中识别一名访客，在 Conversations SDK 之外没有任何作用。

Requirements

要求

RequirementDetail
Account tierProfessional or Enterprise
Required scope
conversations.visitor_identification.tokens.create
Token lifetime12 hours; cache across page loads and refresh at least every 12 hours
Generation sideServer-side only — never generate in browser JavaScript; your private app token must remain secret
要求详细信息
账户套餐Professional 或 Enterprise
所需 scope
conversations.visitor_identification.tokens.create
token 有效期12 小时；可以跨页面加载缓存，并且至少每 12 小时刷新一次
生成端仅限服务端——绝不要在浏览器 JavaScript 中生成；你的私有应用 token 必须保密

Generate a token

生成 token

bash
undefined
bash
undefined

Minimal — email only

Minimal — email only

hubspot conversations visitor-identification create-token
--email visitor@example.com
hubspot conversations visitor-identification create-token
--email visitor@example.com

With name (populates the contact preview in the widget)

With name (populates the contact preview in the widget)

hubspot conversations visitor-identification create-token
--email visitor@example.com
--first-name Jane
--last-name Doe

Output:
```json
{"ok":true,"data":{"token":"eyJhbGciOiJIUzI1NiJ9..."}}
If the private app token is missing the required scope the CLI returns a 403 with a scope hint:
json
{"ok":false,"error":{"status":403,"message":"Missing scope: conversations.visitor_identification.tokens.create"}}
hubspot conversations visitor-identification create-token
--email visitor@example.com
--first-name Jane
--last-name Doe

输出：
```json
{"ok":true,"data":{"token":"eyJhbGciOiJIUzI1NiJ9..."}}
如果私有应用 token 缺少所需 scope，CLI 将返回 403 以及 scope 提示：
json
{"ok":false,"error":{"status":403,"message":"Missing scope: conversations.visitor_identification.tokens.create"}}

Setting up the private app token

配置私有应用 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
必须在 token 所对应的 HubSpot 私有应用上授予 
conversations.visitor_identification.tokens.create
scope，其中该 token 存储在 
HUBSPOT_ACCESS_TOKEN
中。要添加此 scope：
  1. 在 HubSpot 中：Settings → Integrations → Private Apps → [your app] → Scopes
  2. 在“CRM”下，启用 
    conversations.visitor_identification.tokens.create
  3. 如果需要，请在更改 scope 后轮换 token

What the frontend must do with the token

前端必须如何使用 token

After generating the token server-side, set 
loadImmediately: false
before the widget loads. Then set the identification properties and load the widget:
javascript
const { token } = await fetch('/api/hs-visitor-token').then(r => r.json());

window.hsConversationsSettings = {
  loadImmediately: false,
  identificationEmail: 'visitor@example.com',
  identificationToken: token,
};

window.HubSpotConversations.widget.load();
Key rules:
  • Generate the token server-side for authenticated users; cache it across page loads only if it is refreshed at least every 12 hours.
  • Do not expose your 
    HUBSPOT_ACCESS_TOKEN
    (private app token) to the frontend.
  • identificationEmail
    must match the email used to generate the token.
See HubSpot's public documentation for the full Conversations SDK reference.
在服务端生成 token 后，应在加载组件之前设置 
loadImmediately: false
。然后设置 identification 属性并加载组件：
javascript
const { token } = await fetch('/api/hs-visitor-token').then(r => r.json());

window.hsConversationsSettings = {
  loadImmediately: false,
  identificationEmail: 'visitor@example.com',
  identificationToken: token,
};

window.HubSpotConversations.widget.load();
关键规则：
  • 为已认证用户在服务端生成 token；只有在确保至少每 12 小时刷新一次的情况下，才可以跨页面加载缓存 token。
  • 不要向前端暴露你的 
    HUBSPOT_ACCESS_TOKEN
    （私有应用 token）。
  • identificationEmail
    必须与生成 token 时使用的邮箱一致。
有关完整的 Conversations SDK 参考信息，请参阅 HubSpot 的公开文档。

Known constraints

已知限制

  • Requires Professional or Enterprise HubSpot subscription. On Starter or Free the API returns a 403.
  • One token per email address per call. Bulk generation is not supported.
  • The token payload is opaque — do not attempt to decode or store it beyond passing it to the SDK.
  • 需要 Professional 或 Enterprise HubSpot 订阅。在 Starter 或 Free 套餐下，API 将返回 403。
  • 每次调用针对一个邮箱地址只能生成一个 token，不支持批量生成。
  • token 的 payload 是不透明的——除传递给 SDK 外，不要尝试对其进行解码或存储。