mcpField
V
visitor-identification

visitor-identification

github.com/hubspot开发28192 次安装今天更新
代码仓库

关于 visitor-identification

这是一个用于 HubSpot Conversations 聊天组件的访客识别令牌生成技能。它面向服务端使用，可将已知访客的聊天会话关联到其 CRM 联系人记录。

主要功能

  1. 01根据邮箱生成令牌
  2. 02可选加入访客姓名
  3. 03生成用于聊天识别的短期令牌
  4. 04说明组件配置与令牌处理

适用场景

  1. 01将已登录访客的聊天关联到 CRM 联系人
  2. 02在聊天组件预览中显示联系人信息

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/hubspot/agent-cli-skills --skill visitor-identification

安装后在 Claude Code 中输入/visitor-identification确认已加载。

详细介绍

需要使用 hub-cli PR #251 中的 conversations 命令组。hubspot conversations visitor-identification --help 提供的信息为准。

访客身份识别简介

已知联系人（即你已掌握其电子邮件地址的人）访问你的网站时，HubSpot Conversations 聊天小组件可以识别他们，并将实时聊天会话关联到其 CRM 记录。为此，你的服务端会生成一个短期有效的签名令牌，并将其传递给 HubSpot Conversations JavaScript SDK。SDK 会将令牌发送给 HubSpot；HubSpot 验证令牌后，将聊天会话与联系人关联起来。

该令牌不是通用身份验证凭据。它只用于识别单个聊天会话中的一位访客，在 Conversations SDK 之外毫无用处。

要求

要求详情
账户套餐Professional 或 Enterprise
必需的权限范围conversations.visitor_identification.tokens.create
令牌有效期12 小时；在页面加载期间缓存，并至少每 12 小时刷新一次
生成端仅限服务端——切勿在浏览器 JavaScript 中生成；必须对私有应用令牌保密

生成令牌

# 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

输出：

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

如果私有应用令牌缺少所需的权限范围，CLI 会返回 403 错误并提示所需的权限范围：

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

设置私有应用令牌

必须在 HUBSPOT_ACCESS_TOKEN 中所配置令牌所属的 HubSpot 私有应用上授予 conversations.visitor_identification.tokens.create 权限范围。添加该权限范围的步骤：

  1. 在 HubSpot 中：设置 → 集成 → 私有应用 → [你的应用] → 权限范围
  2. 在“CRM”下，启用 conversations.visitor_identification.tokens.create
  3. 如果更改权限范围后需要，请轮换令牌

前端如何使用令牌

在服务端生成令牌后，在小组件加载前设置 loadImmediately: false。然后设置身份识别属性并加载小组件：

const { token } = await fetch('/api/hs-visitor-token').then(r => r.json());

window.hsConversationsSettings = {
  loadImmediately: false,
  identificationEmail: '[email protected]',
  identificationToken: token,
};

window.HubSpotConversations.widget.load();

关键规则：

  • 为已通过身份验证的用户在服务端生成令牌；只有至少每 12 小时刷新一次，才能在页面加载期间缓存令牌。
  • 不要向前端暴露 HUBSPOT_ACCESS_TOKEN（私有应用令牌）。
  • identificationEmail 必须与生成令牌时使用的电子邮件地址一致。

完整的 Conversations SDK 参考信息，请参阅 HubSpot 的公开文档。

已知限制

  • 需要 HubSpot Professional 或 Enterprise 订阅。使用 Starter 或 Free 时，API 会返回 403。
  • 每次调用只能为一个电子邮件地址生成一个令牌。不支持批量生成。
  • 令牌负载不透明——不要尝试解码，也不要将其存储；只需将其传递给 SDK。

评论

支持 Markdown