mcpField
V
visitor-identification

visitor-identification

github.com/hubspot開発28192 回インストール今日更新
リポジトリ

visitor-identification について

HubSpot Conversationsのチャットウィジェット向けに、訪問者識別トークンを生成するCLIスキルです。サーバー側で利用し、既知の訪問者のチャットセッションを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 がそれを検証して、チャットセッションをコンタクトに関連付けます。

トークンは一般的な認証情報ではありません。これは 1 回のチャットセッションに対して 1 人の訪問者を識別するものであり、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"}}

プライベートアプリのトークンを設定する

conversations.visitor_identification.tokens.create スコープは、HUBSPOT_ACCESS_TOKEN にトークンが設定されている HubSpot プライベートアプリに対して付与されている必要があります。スコープを追加するには:

  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 を返します。
  • 1 回の呼び出しにつき、1 つのメールアドレスに対して 1 つのトークンです。一括生成はサポートされていません。
  • トークンのペイロードは不透明です — SDK に渡す以外の目的でデコードしたり保存したりしないでください。

コメント

Markdown 対応