コミュニケーションSDK

HubSpotのウェブ チャット ウィジェットを使用すると、自社のウェブサイト上で顧客やリードとチャットできます。チャットウィジェットSDKを使用してチャットウィジェットの動作をカスタマイズすることで、1人ひとりの訪問者に合わせた最適な顧客体験を提供できます。

使用例：チャットウィジェットSDKを使用して、HubSpotのチャットウィジェットがウェブサイト上に表示されるタイミングや形式をカスタマイズできます。

主に次のような処理に活用できます。

はじめに

本APIはwindow.HubSpotConversationsオブジェクトに実装されています。使用可能な全てのメソッドは、このオブジェクトを介して利用します。このオブジェクトはページ上のHubSpotスクリプトローダー（通称HubSpotトラッキングコード）によって自動的に作成されますが、即座に利用可能にならない場合もあります。初期化の完了までの間、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

windowオブジェクトに定義できるこの特殊なフィールドを使用すると、ウィジェットの利用が可能になった際に起動されるコードを指定できます。このプロパティーの使用は任意です。使用する場合は、このフィールドに関数の配列を割り当てる必要があります。APIが初期化されると、この配列の有無が確認され、存在する場合は配列に含まれる一連の関数が逐次実行されます。例：

if (window.HubSpotConversations) { console.log('The api is ready already'); } else { window.hsConversationsOnReady = [ () => { console.log('Now the api is ready'); }, ]; }

hsConversationsSettings

このオブジェクトを使用して、ウィジェットの初期化が行われる前に、設定オプションを提供できます。このオブジェクトの使用は任意です。

フィールド
フィールド名 データ型 既定値  説明

loadImmediately

 

 ブール true ウィジェットを暗黙的に読み込むか、またはwidget.loadメソッドが呼び出されるまで読み込みを待機するかを指定します。
inlineEmbedSelector 文字列 "" ページ内でのウィジェットの埋め込み箇所。セレクター（#some-idなど）を指定すると、該当するDOMノード内にウィジェットがインラインで埋め込まれます。また、widget.removeを使用して取り除くまでの間、開いた状態が維持されます。
enableWidgetCookieBanner 列挙 false ページ上の全てのチャットフローに関するCookieバナーの動作を制御します。

false - チャットフローの設定を適用します（既定）。

true - ウィジェットが読み込まれた際のCookieバナーを有効にします。

ON_WIDGET_LOAD - trueと同じ。ウィジェットが読み込まれた際のCookieバナーを有効にします。

ON_EXIT_INTENT - ユーザーがチャット終了の意図を示した際のCookieバナーを有効にします。


なお、このフィールドは従来、Booleanでした。現在は、当初のBoolean値と新たなenum値の両方に対応しています。
disableAttachment ブール false チャットウィジェット内で添付ファイルのアップロードボタンを非表示にするかどうかを指定します。
 
window.hsConversationsSettings = { loadImmediately: false, inlineEmbedSelector: '#some-id', enableWidgetCookieBanner: true, disableAttachment: true }; window.hsConversationsOnReady = [ () => { window.HubSpotConversations.widget.load(); }, ];

インライン埋め込みスタイル

window.hsConversationsOnReady

具体的な場所を指定してウィジェットを埋め込むと複数のDOM要素が追加されるため、貴社のカスタマイズ要件（高さ、幅、境界線など）に合わせてスタイルを設定できます。この構造は、inlineEmbedSelectorオプションを使用した場合にのみ適用されることにご留意ください

<div id="hubspot-conversations-inline-parent">
<iframe id="hubspot-conversations-inline-iframe" />
</div>

例えば、このチャットウィジェットは既定で次のように表示されます。

livechat_before

 

このように窮屈なレイアウトは望ましくない場合、次のようなスタイルを組み込んでウィジェットをカスタマイズできます。


#hubspot-conversations-inline-iframe {
width: 300px;
height: 500px;
border:none;
}

livechat_after

これにより、ユーザーエクスペリエンスが大幅に向上します。

 

HubSpotConversations.widget

widgetオブジェクトには、ページ上のチャットウィジェットを操作するための数多くのメソッドが実装されています。

widget.load

ページに初めてウィジェットを読み込みます。ウィジェットが読み込み済みの場合、このメソッドに対する以降の呼び出しはno-op（操作なし）命令になり、何も行われません。

このメソッドが必要になるのは、loadImmediatelyフラグをfalseに設定した場合に限られます。それ以外の場合、ウィジェットは自動的に読み込まれます。

注： widget.loadの呼び出し頻度は1秒につき1回です。

パラメーター：
フィールド名 データ型 既定値 説明
widgetOpen ブール false ウィジェットを開いた状態で読み込むかどうかを指定します。
 
window.HubSpotConversations.widget.load(); /* ... */ // Force the widget to load in an open state window.HubSpotConversations.widget.load({ widgetOpen: true });

widget.refresh

現在のページURLを基に、ウィジェットの情報を再度読み込んでレンダリングし直します。

単一ページのアプリにチャットウィジェットを設置している場合、このメソッドはルート変更に基づくウィジェットの再読み込みに役立ちます。これにより、ページルートごとに異なるチャットフローを設定できます。チャットフローがないルートに対してwidget.refreshが呼び出され、ユーザーがコミュニケーションを利用していない場合は、ウィジェットは取り除かれます。

注：widget.refreshの呼び出し頻度は1秒につき1回です。

パラメーター：
フィールド名 データ型 既定値 説明
openToNewThread ブール false 新しいスレッドを作成するかどうかを指定します。

openToNewThreadフィールドの使用例については、特定のチャットフローを開く（英語）を参照してください。

例：
window.HubSpotConversations.widget.refresh(); /* ... */ // Force the widget to open to a specific chat flow window.HubSpotConversations.widget.refresh({ openToNewThread: true });

注： widget.refreshでは、ページ訪問者が開始したウィジェット上の既存のコミュニケーションは削除されません。

 

widget.open

ウィジェットを開きます。ウィジェットがすでに開かれているか、現在読み込まれていない場合は、no-op（操作なし）命令になり、何も行われません。

例：
window.HubSpotConversations.widget.open();

widget.close

ウィジェットを閉じます。ウィジェットがすでに閉じられているか、現在読み込まれていない場合は、no-op（操作なし）命令になり、何も行われません。

例：
window.HubSpotConversations.widget.close();

widget.remove

ページからウィジェットを取り除きます。ページ上にウィジェットが存在しない場合は、no-op（操作なし）命令になり、何も行われません。ウィジェットを再度表示するには、ページ全体を読み込み直す必要があります。または、widget.loadを呼び出すことも可能です。

例：
window.HubSpotConversations.widget.remove();

widget.status

ウィジェットのステータスに関連するプロパティーを格納したオブジェクトが返されます。

フィールド名 データ型 既定値 説明
loaded ブール false ウィジェットのiframeが読み込まれているかどうかを指定します。

 

例：
const status = window.HubSpotConversations.widget.status(); if (status.loaded) { window.HubSpotConversations.widget.refresh(); } else { window.HubSpotConversations.widget.load(); }

clear

チャットウィジェットでは、サイト訪問やページの再読み込みが繰り返されても状態を維持できるように、複数のCookieが作成されます。このようなCookieはウィジェットのホスティング先ページのドメインを対象に、以下の機能を有効にするために使用されます。

  • 過去のコミュニケーションを参照する
  • ページ読み込みが繰り返されてもチャットウィジェットを開いた状態に維持する
  • ページ読み込みが繰り返されても歓迎メッセージを開いた状態に維持する

clearメソッドを使用することで、これらのCookieを削除し、以降の読み込み時にウィジェットを既定の状態に戻すことができます。

このメソッドにより、以下のCookieが消去されます。

  • messagesUtk
  • hs-messages-is-open
  • hs-messages-hide-welcome-message

このようなCookieの詳細については、このナレッジベースの記事を参照してください。

例：
window.HubSpotConversations.clear();

さらに、{resetWidget:true}をclear()関数に渡すことで、チャット関連の全てのCookieを消去し、ページからウィジェットを取り除いた上で、チャットウィジェットの新しいインスタンスを作成できます。

例：
window.HubSpotConversations.clear({resetWidget:true});

Event specification

チャットウィジェットからは、ライフサイクル全体にわたって各種のイベントが送信されます。このイベントを検知し、応答することができます。

 

サポートされるイベント

conversationStarted

新しいコミュニケーションが正常に開始されると、送信されます。

イベントのペイロード
フィールド名 データ型 説明
conversation コミュニケーション（英語） 開始されたコミュニケーションの詳細

 

例：
window.HubSpotConversations.on('conversationStarted', payload => { console.log( `Started conversation with id ${payload.conversation.conversationId}` ); });

conversationClosed

新しいコミュニケーションが正常にクローズされると送信されます。

注：このイベントは、コミュニケーションの受信トレイからコミュニケーションがクローズされると発生します。ユーザーによってチャットウィジェットが最小化されたり閉じられたりすることとは関係ありません。

 

イベントのペイロード
フィールド名 データ型 説明
conversation コミュニケーション（英語） クローズされたコミュニケーションの詳細

 

例：
window.HubSpotConversations.on('conversationClosed', payload => { console.log( `Conversation with id ${ payload.conversation.conversationId } has been closed!` ); });

unreadConversationCountChanged

ウィジェット内の未読メッセージを含むコミュニケーションの数が変化（増減）すると送信されます。

イベントのペイロード
フィールド名 データ型 説明
unreadCount 数値 ウィジェットでの未読メッセージを含む新しいコミュニケーションの合計数

 

例：
window.HubSpotConversations.on('unreadConversationCountChanged', payload => { console.log(`New unread count is ${payload.unreadCount}!`); });

contactAssociated

訪問者がCRM内のコンタクトと関連付けられると、送信されます。 

イベントのペイロード
フィールド名 データ型 説明
message 文字列 訪問者がコンタクトと関連付けられたことに関する確認メッセージ
例：
window.HubSpotConversations.on(‘contactAssociated’, payload => { console.log(payload.message); });

on

イベントリスナーを登録します。サポートされるイベントタイプ（英語）を参照してください。

例：
window.HubSpotConversations.on('conversationStarted', payload => { console.log(payload); });

off

イベントリスナーを取り除きます。サポートされるイベントタイプを参照してください。

例：
const handleEvent = eventPayload => console.log(eventPayload); window.HubSpotConversations.on('conversationStarted', handleEvent); /* ... */ window.HubSpotConversations.off('conversationStarted', handleEvent);

データ型

JavaScript SDKと共通のデータ型のリファレンスは、以下の通りです。

コミュニケーション
フィールド名 データ型 説明
conversationId 数値 コミュニケーションのID。
参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。