サポートされる製品
次のいずれかの製品またはそれ以上が必要です。
Marketing HubMarketing HubProfessional
Sales HubSales HubProfessional
Service HubService HubProfessional
Content HubContent HubProfessional
最終更新日: 2025年8月22日
訪問者の識別APIを使用することで、独自の外部認証システムによって認証されたサイト訪問者を識別します。 このAPIから返される識別トークンを使用し、すでに認証された訪問者に関する情報をチャットウィジェットに渡すことで、訪問者が既知のコンタクトとして扱われるようになります。受信トレイのエージェントは誰とやりとりしているかを明確に把握でき、訪問者は複数のデバイス間で過去のスレッド履歴にアクセスできます。 例えば、ログインが必要な独自のWebアプリをホスティングする場合、Webアプリ内のページに、HubSpotのチャットウィジェットが表示されるようにセットアップするかもしれません。Webアプリ内の訪問者は、既に認証されて識別されています。しかし現在のところ、Webアプリで識別されているログイン中の訪問者であっても、そのページ内でチャットをしている訪問者は、コミュニケーションの受信トレイで「不明な訪問者」として表示されます。訪問者の識別APIを使用すると、認証された訪問者の情報を直接チャットウィジェットに渡し、これらの訪問者がコミュニケーション受信トレイで識別されるようにすることができます。
注:
  • 訪問者の識別APIの目的は、訪問者が誰であるかをHubSpotに伝えることです。プラットフォーム内のユーザーを認証する上で、この機能を利用すべきではありません。
  • 訪問者の識別APIを利用するには、ProfessionalまたはEnterpriseエディションのサブスクリプションが必要です。アカウントに適格なサブスクリプションがない場合、APIから403エラーレスポンスが返されます。

​
連携フローの例

訪問者の識別機能との連携を使用するには、認証システムを備えた既存のWebアプリケーションが必要です。開始する前に、非公開アプリがセットアップされていること、また、対象となるProfessionalまたはEnterpriseエディションが、連携しようとしているアカウントで使用されていることを確認してください。 以下に、考えられる連携フローの例を示します。
考えられるユーザー識別フロー
顧客がシステムにログインして認証されたら、次の手順に従って、ウェブチャットで顧客を識別します。 1. フロントエンドで、ウィンドウ上のhsConversationsSettingsオブジェクトのloadImmediatelyをfalseに設定します。このように設定しないと、識別情報が渡される前にチャットウィジェットが読み込まれる場合があります。詳細については、以下のチャットウィジェットSDK入門をご確認ください。
  • isConversationsAPIReady関数の外側でhsConversationsSettingsプロパティーを設定します。
  • さらに、hsConversationsSettingsを呼び出し前に設定する必要があります。そうしないと、競合状態が発生してウィジェットの読み込みが妨げられる可能性があります。
window.hsConversationsSettings = {
  loadImmediately: false,
};
2. 認証済み訪問者のEメールアドレスを訪問者識別APIに渡すことで、トークンを生成します。この操作は、Webアプリケーションのバックエンドで行う必要があります。リクエストの例については、エンドポイントのリファレンスドキュメントをご参照ください。 
curl --request POST \
  --url 'https://api.hubspot.com/conversations/v3/visitor-identification/tokens/create \
--data '{
  "email": "gob@bluth.com",
  "firstName": "Gob",
  "lastName": "Bluth"
}'
以下が該当する場合、提供された氏名は、チャット開始後にHubSpotのコンタクトレコードで設定されます。
  • 訪問者の識別APIによって作成された新しいコンタクトであるｖ名前がまだ分かっていない既存のコンタクトである
外部システムにはすでに名前の情報がある一方、HubSpotにはまだ存在しない場合、識別された訪問者へのメッセージをパーソナライズするときに役立ちます。これらは任意指定のパラメーターであり、必須ではありません。
3. ステップ2のトークンを使用して、ウィンドウ上のhsConversationsSettingsオブジェクトに次のプロパティーを設定します。 
window.hsConversationsSettings = {
  identificationEmail: 'visitor-email@example.com',
  identificationToken: '<TOKEN FROM STEP 1>',
};
4. ウィジェットを読み込みます。 
window.HubSpotConversations.widget.load();
認証された訪問者のページが読み込まれるたびに、ウィンドウ上のhsConversationsSettingsオブジェクトにトークンとEメールが設定される必要があります。これらのパラメーターが設定されなくなると、以降のページの読み込み時に、コンテキストは自動的に保持されません。トークンは一時的なもので、12時間後に期限切れになります。トークンが少なくとも12時間に1回更新される場合、トークンをキャッシュして、ページを読み込むたびにトークンを再取得しなくて済むようにできます。

​
連携を確認する

訪問者の識別機能との連携が完了したら、連携が想定通りに機能していることを確認します。以下に示すように、実装に応じて2通りの方法で確認できます。具体的な要件に合わせて、以下の例を調整する必要がある場合があります。
  • 1つ以上の公開ページ上および認証システムの背後にチャットウィジェットをすでに追加している場合：
    • チャットウィジェットで訪問者を識別しないページに移動し、コミュニケーションを開始します。
    • HubSpotで受信トレイを開き、受信したチャットが「不明な訪問者」に属していることを確認します。そうでない場合は、非公開のブラウザーウィンドウで次の手順を試してみてください。
      • チャットウィジェットで訪問者識別APIを使用して訪問者を識別するページに移動し、コミュニケーションを開始します。
      • HubSpotで受信トレイを開き、ログインに使用したコンタクトにチャットが属性として正しく結び付けられていることを確認します。正しい関連付けが確認された場合、コンタクトの名前の横に、このコンタクトが訪問者の識別APIで正常に識別されたことを示すバッジが表示されます。
visitor_identity_badge
  • 認証システムの背後にあるページにのみチャットウィジェットを追加済みであり、複数のテスト ユーザー アカウントにアクセスできる場合:
    • 最初のテストユーザーとしてHubSpotにログインし、チャットウィジェットが読み込まれるページに移動して、コミュニケーションを開始します。
    • HubSpotからログアウトし、2番目のテストユーザーとして再度ログインします。チャットウィジェットが読み込まれるページに移動し、コミュニケーションを開始します。
    • HubSpotで受信トレイを開き、最初のテストアカウントと2番目のテストアカウントからそれぞれチャットが送信されていて、両方のレコードでコンタクト名の横にバッジが表示されていることを確認します。
注: このAPIで識別された訪問者に関して、HubSpotはmessagesUtk Cookieをドロップしません。また、Eメールアドレスは既知であることから、HubSpotはEメールキャプチャーの質問をスキップします。messagesUtk CookieとEメールキャプチャーはこれらのチャットには適用されないため、訪問者の識別APIを介して識別された訪問者に関しては、チャットフローの関連設定が表示されません。

​
チャットウィジェットSDK入門

このAPIはwindow.HubSpotConversationsオブジェクトに格納されています。使用可能な全てのメソッドは、このオブジェクトを介して利用されます。このオブジェクトはページ上のHubSpotスクリプトローダーによって自動的に作成されますが、直ちに利用可能にならない場合もあります。APIが初期化されるまでの間、APIへのアクセスを遅延させるには、window.hsConversationsOnReadyヘルパーを使用できます。以下に例を示します。 
<script type="text/javascript">
  function onConversationsAPIReady() {
    console.log(`HubSpot Conversations API: ${window.HubSpotConversations}`);
  }
  /*
    configure window.hsConversationsSettings if needed.
  */
  window.hsConversationsSettings = {};
  /*
   If external API methods are already available, use them.
  */
  if (window.HubSpotConversations) {
    onConversationsAPIReady();
  } else {
    /*
      Otherwise, callbacks can be added to the hsConversationsOnReady on the window object.
      These callbacks will be called once the external API has been initialized.
    */
    window.hsConversationsOnReady = [onConversationsAPIReady];
  }
</script>

​
SDKリファレンス

window.hsConversationsOnReady 配列 これは、ウィンドウオブジェクトで定義できる任意指定のフィールドです。これを使用すると、ウィジェットが使用可能になったらすぐに実行されるコードを指定できます。APIが初期化されると、この配列の有無が確認され、存在する場合は配列に含まれる一連の関数が実行されます。 
if (window.HubSpotConversations) {
  console.log('The api is ready already');
} else {
  window.hsConversationsOnReady = [
    () => {
      console.log('Now the api is ready');
    },
  ];
}
hsConversationsSettings オブジェクト このオブジェクトを使用すると、設定オプションを指定してからウィジェットを初期化できます。訪問者の識別機能を使用するには、次のフィールドを設定する必要があります。
パラメータータイプ説明既定値
loadImmediatelyブール値ウィジェットを暗黙的に読み込むか、それともwidget.loadメソッドが呼び出されるまで待つかtrue
identificationToken文字列訪問者識別APIとの連携に使用されます。訪問者の識別API上のトークン生成エンドポイントによって提供されるトークンであり、これを使用してこの訪問者が認証済みであることを証明します。""
identificationEmail文字列ウィジェットの読み込み中であることがすでに識別された訪問者のメールアドレス。""
window.hsConversationsSettings = {
  loadImmediately: false,
  identificationEmail: 'visitor-email@example.com',
  identificationToken: '<TOKEN FROM STEP 1>',
};
詳しくはコミュニケーションSDKをご確認ください。