用途:当已知联系人(已有邮箱)访问网站时,让 HubSpot Conversations 聊天挂件把会话关联到其 CRM 记录。做法是服务端生成短期签名令牌,交给 Conversations JavaScript SDK,由 HubSpot 验证后关联会话。该令牌不是通用凭证,只对一次聊天会话的一名访客有效。
主要能力:按邮箱生成访客识别令牌,可附带名(--first-name)和姓(--last-name)以填充挂件中的联系人预览。命令:hubspot conversations visitor-identification create-token --email visitor@example.com;带姓名时加 --first-name Jane --last-name Doe。输出形如 {"ok":true,"data":{"token":"..."}}。缺少所需权限时返回 403,并提示缺失的 scope。
使用要求:需 Professional 或 Enterprise 账户,Free 或 Starter 会返回 403;所需权限为 conversations.visitor_identification.tokens.create;令牌有效期 12 小时,需在页面加载间缓存并至少每 12 小时刷新;只能在服务端生成,私应用令牌必须保密。权限需在 HubSpot 私应用(其令牌存于 HUBSPOT_ACCESS_TOKEN)中授予,路径为 Settings → Integrations → Private Apps → 应用 → Scopes,在 CRM 下启用该 scope,更改后如需可轮换令牌。前端需在挂件加载前设置 loadImmediately: false,再设置 identificationEmail 与 identificationToken 并调用 window.HubSpotConversations.widget.load();identificationEmail 必须与生成令牌所用邮箱一致。
限制:每个邮箱每次调用只能生成一个令牌,不支持批量;令牌载荷不透明,不要解码或另行存储,只传给 SDK;具体命令行为以 hubspot conversations visitor-identification --help 为准,该命令组依赖 hub-cli PR #251。完整 SDK 参考见 HubSpot 公开文档。