Klaviyo Customer Hub JavaScript API リファレンス

このページで学べること

window.customerHubApi JavaScript API を使用して、自社のストアフロント コードから Customer Hub（またはスタンドアロンの Klaviyo ウェブチャット）を制御する方法。エクスペリエンスの開始と終了、特定の画面への移動、買い物客に代わってチャットメッセージを送信、カート追加などのイベントをリッスンできます。

始める前に

必要なもの：

• Klaviyo Customer Hub がストアフロントに設定され、読み込まれています。ヘッドレスまたはカスタムのストアフロントを使用している場合は、まず ヘッドレス Shopify で Klaviyo Customer Hub を設定する方法 に従ってください。ここでは、この API を使用可能にするオンサイト ローダーの追加について説明しています。
• ストアフロントのコードを編集してデプロイできる機能。

Klaviyo Customer Hub API とは

ストアフロントで Klaviyo Customer Hub、または単独の Klaviyo ウェブチャットが読み込まれるたびに、Klaviyo はグローバル window オブジェクトに小さな JavaScript API を window.customerHubApi としてアタッチします。これを使用して、独自のコードからエクスペリエンスを開く、閉じる、または操作できます。たとえば、カスタムボタン、バナー、または商品ページから操作できます。

if (window.customerHubApi) {
  window.customerHubApi.open();
}

方法

open(route?)

Klaviyo Customer Hub ドロワーを開きます。

• route (string, optional) — 開くときに移動するパスです。省略すると、Hub は最後に表示していた画面で開きます。

// Open the Hub on its default screen
window.customerHubApi.open();

// Open the Hub directly to a specific screen
window.customerHubApi.open('/orders');

利用可能なルート

close()

Klaviyo Customer Hub のドロワーを閉じます。ハブは現在の画面に留まるため、open()（ルートなし）で再度開くと、顧客は離れた場所に戻ります。

window.customerHubApi.close();

sendChatMessage(message)

[チャット] 画面で Klaviyo Customer Hub を開き、お客様に代わってメッセージを送信します。これは、「この商品についてチャットする」や「ヘルプを受ける」ボタンに便利です。

• message (string) — 送信するメッセージ。

window.customerHubApi.sendChatMessage('I have a question about my order.');

ログインが必要な場合：ストアでチャット前に顧客のログインが必須（かつ AI エージェントが有効でない）場合、顧客は最初にログインするためにチャット画面へ移動します。メッセージは一時的に保存され、ログインが完了すると自動的に送信されます。ログインが完了しない場合、保存されたメッセージは約 10 分後に期限切れになります。

sendConversationContext(context)

チャット会話の外部で収集されたバックグラウンドコンテキスト（チャット前アンケートの回答など）をキューに入れ、お客様の次のチャットメッセージとともに送信します。Klaviyoはその後、このコンテキストを保存し、その会話の残りの間参照します。

• context（オブジェクト） — entries 配列を含むアンケート回答オブジェクト。各エントリには question と answer を必ず含める必要があります。

window.customerHubApi.sendConversationContext({
  type: 'survey-response',
  entries: [
    { question: 'What color are you interested in?', answer: 'Red' },
  ],
});

getActiveConversationId()

ドロワーで行われているアクティブな会話の conversationId を返します。会話が進行中でない場合は null を返します。

window.customerHubApi.getActiveConversationId();

イベントをリッスンする

window.customerHubApi.events Klaviyo Customer Hub 内で発生するイベントを購読できます。

addtocart

Hub 内でお客様が商品をカートに追加したときに起動します。ストアフロントのカートを同期した状態に保つために使用します。

window.customerHubApi.events.addEventListener('addtocart', (event) => {
  // event.detail.items is an array of { variantId, quantity }
  event.detail.items.forEach((item) => {
    console.log('Added to cart:', item.variantId, 'x', item.quantity);
  });
});

完全な例

Hub を開いてメッセージを送信する [この商品についてチャット] ボタンに加え、Hub から購入者がアイテムを追加したときにストアフロントのカートを同期するリスナー：

<button id="ask-about-product">Ask us about this product</button>

<script>
  document
    .getElementById('ask-about-product')
    .addEventListener('click', () => {
      if (window.customerHubApi) {
        window.customerHubApi.sendChatMessage(
          'I have a question about this product.'
        );
      }
    });

  // Sync the storefront cart when a customer adds an item from the Hub
  if (window.customerHubApi) {
    window.customerHubApi.events.addEventListener('addtocart', (event) => {
      refreshStorefrontCart(event.detail.items);
    });
  }
</script>

その他のリソース