コミュニケーションSDK

HubSpotのコミュニケーションの受信トレイを使用してウェブサイトで顧客やリードとチャットするには、ライブ チャット ウィジェットを設定できます。コミュニケーションSDKを使用してチャットウィジェットの動作をカスタマイズすることで、1人ひとりの訪問者に合わせた最適な顧客体験を提供できます。

コミュニケーションSDKを使用すると、主に次の操作を実行できます。

初期化

APIはwindow.HubSpotConversationsオブジェクトに実装されており、使用可能な全てのメソッドへのアクセスを提供します。オブジェクトはHubSpotトラッキングコードによって作成されますが、ページの読み込み時にすぐには使用できない場合があります。初期化の完了までの間、APIへのアクセスを遅延させるには、window.hsConversationsOnReadyヘルパーを使用できます。

window.hsConversationsOnReadyはwindowオブジェクトに定義できるオプションのフィールドで、このフィールドを使用すると、ウィジェットの利用が可能になった際に起動されるコードを指定できます。このフィールドは、APIが初期化されると実行される配列関数を取ります。

<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>

コミュニケーション設定を構成する

hsConversationsSettings

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

window.hsConversationsSettings = { loadImmediately: false, inlineEmbedSelector: '#some-id', enableWidgetCookieBanner: true, disableAttachment: true }; window.hsConversationsOnReady = [ () => { window.HubSpotConversations.widget.load(); }, ];
Field Type Default Description
loadImmediately Boolean true Whether the widget should implicitly load or wait until the widget.load method is called.
inlineEmbedSelector String "" Specify a selector  (#some-id) to embed the chat widget in a specific location on the page. Widget will be embedded inline within that DOM node and will remain open until it is removed with widget.remove. Learn more about styling embedded chat widgets.
enableWidgetCookieBanner Enumeration false Control behavior of the cookie banner for all chat widgets on the page. Options include:
  • false (default): uses the chat widget's settings.
  • true: presents cookie banners when the widget is loaded.
  • ON_WIDGET_LOAD: same as true.
  • ON_EXIT_INTENT: enable cookie banners when the user exhibits an exit intent.
disableAttachment Boolean false Whether to hide the upload attachment button in the chat widget.
disableInitialInputFocus Boolean false Whether to automatically prevent focusing on the widget's input field after an inline embedded widget is initially loaded.

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

inlineEmbedSelectorを使用して具体的な場所を指定してウィジェットを埋め込むと、複数のDOM要素が追加されるため、スタイル（高さ、幅、境界線など）を設定できます。 

例えば、#some-idセレクターを使用してチャットウィジェットを埋め込むと、次のコンテナーとIDが読み込まれます。

<div id="some-id"> <div id="hubspot-conversations-inline-parent"> <iframe id="hubspot-conversations-inline-iframe"> <!-- rest of iframe content --> </iframe> </div> </div>

You can then customize the chat widget using those selectors, such as:

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

livechat_after

 

Widget behavior

HubSpotConversations.widget

The widget object contains a number of methods that allow you to manipulate the chat widget on your page, including:

Below, learn more about each method.

widget.load

The widget.load method handles the initial load on the page. This method is only necessary if you set loadImmediately to false. Otherwise, the widget will load itself automatically.

This method is throttled to one call per second.

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

widget.refresh

widget.refreshメソッドは、現在のページURLを基に、ウィジェットの情報を再度読み込んでレンダリングし直す処理を行います。単一ページのアプリにチャットウィジェットを埋め込んでいる場合、このメソッドはルート変更に基づくウィジェットの再読み込みが必要なときに役立ちます。このメソッドを使用すると、ページルートごとに異なるチャットウィジェットを指定することもできます。

チャットウィジェットがないルートに対してwidget.refreshを呼び出し、ユーザーがチャットを利用していない場合は、ウィジェットは取り除かれます。現在アクティブなチャットがある場合、ウィジェットは削除されません。

このメソッドの呼び出し頻度は1秒につき1回です。

window.HubSpotConversations.widget.refresh(); /* ... */ // Force the widget to open to a specific chat flow window.HubSpotConversations.widget.refresh({ openToNewThread: true });
フィールド 型 既定 説明
openToNewThread ブール値 false 新しいスレッドを作成するかどうかを指定します。 

例

このメソッドを使用すると、ページURLにクエリーパラメーターを追加することで、ページ上の特定のチャットフローを開くためのボタンとリンクを作成できます。

conversations-chat-widget-open-crop例えば、次のコードをページに追加してボタンを生成できます。

<div class="chat-buttons"> <button onclick="window.history.pushState({}, 'talk_to_sales', '?sales_chat=true'); window.HubSpotConversations.widget.refresh({openToNewThread: true});">Talk to sales</button> <button onclick="window.history.pushState({}, 'talk_to_customer_support', '?cs_chat=true'); window.HubSpotConversations.widget.refresh({openToNewThread: true});">Talk to customer support</button> <button onclick="window.history.pushState({}, 'talk_to_the_ceo', '?ceo_chat=true'); window.HubSpotConversations.widget.refresh({openToNewThread: true});">Talk to the CEO</button> </div>

次に、各チャットのターゲット設定で、クエリーパラメーターがボタンコードで設定したものと一致したときに表示されるようにチャットを設定します。
conversations-target-rule

widget.open

widget.openメソッドは、ウィジェットがまだ開いていないか、現在読み込まれていない場合にウィジェットを開きます。

window.HubSpotConversations.widget.open();

widget.close

widget.closeメソッドは、ウィジェットがまだ閉じられていない場合、ウィジェットを閉じます。

window.HubSpotConversations.widget.close();

widget.remove

widget.removeメソッドは、ページからウィジェットを取り除きます。ページ上にウィジェットが存在しない場合は、このメソッドは何も行いません。ウィジェットは、ページの更新時、またはwidget.loadが呼び出された場合に再び表示されます。

window.HubSpotConversations.widget.remove();

widget.status

widget.statusメソッドは、ウィジェットの現在のステータスに関連するプロパティーを含むオブジェクトを返します。

const status = window.HubSpotConversations.widget.status(); if (status.loaded) { window.HubSpotConversations.widget.refresh(); } else { window.HubSpotConversations.widget.load(); }
フィールド 型 既定 説明
loaded ブール値 false ウィジェットのiframeが読み込まれているかどうかを示します。

チャットCookieをクリアする

clearメソッドは、チャットウィジェットに関連するCookieを削除し、その後の読み込みで既定の状態に戻します。

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

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

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

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

これらのCookieの詳細については、HubSpotのナレッジベースをご覧ください。

window.HubSpotConversations.clear();

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

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

チャットイベント

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

イベントリスナーを登録および削除するには、以下に示すようにonとoffを使用します。

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

各イベントの詳細については、以下をご覧ください。

conversationStarted

conversationStartedイベントは、新しいコミュニケーションが正常に開始されるとトリガーされます。

window.HubSpotConversations.on('conversationStarted', payload => { console.log( `Started conversation with id ${payload.conversation.conversationId}` ); });
フィールド 型 説明
conversation スレッドID 開始されたコミュニケーションのスレッドID。このIDは、コミュニケーションAPIへの呼び出し時に使用できます。

conversationClosed

conversationClosedイベントは、新しいコミュニケーションがコミュニケーションの受信トレイでクローズ済みとしてマークされたときにトリガーされます。

チャットウィジェットを最小化するか閉じるサイト訪問者は、このイベントをトリガーしません。この場合のイベントには、代わりにwidgetClosedを使用します。

window.HubSpotConversations.on('conversationClosed', payload => { console.log( `Conversation with id ${ payload.conversation.conversationId } has been closed!` ); });
フィールド 型 説明
conversation スレッドID 開始されたコミュニケーションのスレッドID。このIDは、コミュニケーションAPIへの呼び出し時に使用できます。

unreadConversationCountChanged

unreadConversationCountChangedイベントは、未読メッセージを含むコミュニケーションの数が増加または減少するとトリガーされます。

window.HubSpotConversations.on('unreadConversationCountChanged', payload => { console.log(`New unread count is ${payload.unreadCount}!`); });
フィールド 型 説明
unreadCount 数値 少なくとも1つの未読メッセージを含むコミュニケーションの合計数。

 

contactAssociated

contactAssociatedイベントは、訪問者がCRM内のコンタクトと関連付けられるとトリガーされます。

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

userInteractedWithWidget

userInteractedWithWidgetイベントは、訪問者がクリックしてウィジェットを開いたり、最初のウェルカムメッセージを閉じたりするなど、ウィジェットとやり取りしたときにトリガーされます。

window.HubSpotConversations.on(‘userInteractedWithWidget’, payload => { console.log(payload.message); });
フィールド 型 説明
message 文字列 訪問者がウィジェットとやり取りしたことに関する確認メッセージ。

widgetLoaded

widgetLoadedイベントは、ウィジェットのiframeが読み込まれたときにトリガーされます。

window.HubSpotConversations.on(‘widgetLoaded’, payload => { console.log(payload.message); });
フィールド 型 説明
message 文字列 ウィジェットのiframeが読み込まれたことに関する確認メッセージ。

quickReplyButtonClick

quickReplyButtonClickイベントは、訪問者がボットのコミュニケーションで簡単な返信をクリックしたときにトリガーされます。

フィールド 型 説明
value 配列 クリックされたクイック返信オプションのテキストを含む配列。
window.HubSpotConversations.on('quickReplyButtonClick', event => { console.log(`The text content of the clicked button is ${payload.value[0]}`); });

quick-reply-options-in-bot-conversation

上記のスクリーンショットの例では、3つのクイック返信オプションがボットチャットフローに含まれています。ユーザーが［もっと詳しく］を選択した場合、結果のイベントペイロードは次のようになります。

// Example event payload when a quick reply option is selected { "name": "QUICK_REPLIES", "multiSelect": false, "value": [ "Learn more" ] }

widgetClosed

widgetClosedイベントは、訪問者がチャットウィジェットを閉じたときにトリガーされます。

window.HubSpotConversations.on('widgetClosed', event => { console.log(event); });
フィールド 型 説明
message 文字列 訪問者がチャットウィジェットを閉じたことに関する確認メッセージ。
参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。