"FlowHunt JS APIでリッスンできるイベントは何ですか？"

"FlowHunt JS APIは10のイベントを発行します：onFHChatbotReady、onFHChatbotSessionCreated、onFHChatbotWindowOpened、onFHChatbotWindowClosed、onFHMessageSent、onFHMessageReceived、onFHFormDataSent、onFHFeedback、onFHToolCall、onFHError。これらはwindow.addEventListenerまたはチャットボットマネージャーのコールバックメソッドを使用してサブスクライブできます。"

"デフォルトのチャットボタンを非表示にしてプログラムでチャットボットを開くには？"

"showChatButton: false設定オプションを使用してデフォルトボタンを非表示にし、chatbotManager.openChat()を呼び出して任意のタイミングでチャットボットを開きます。例えば、カスタムボタンのクリック時に開くことができます。"

"マネージャーコールバックメソッドとwindow.addEventListenerの違いは何ですか？"

"どちらの方法も使用できます。マネージャーコールバックメソッド（例：chatbotManager.onMessageSent(fn)）はinitコールバック内で呼び出され、マネージャーインスタンスに紐づけられます。window.addEventListenerアプローチ（例：window.addEventListener('onFHMessageSent', fn)）は、チャットボットの読み込み前でも、ページのどこにでも設定できます。"

"フロー変数を使用してチャットボットにカスタムデータを渡すには？"

"setConfig()のflowVariables設定オプションを使用して、ユーザーID、メールアドレス、ページURLなどのキーと値のペアを渡します。これらの変数はチャットボットフロー内で利用可能になり、パーソナライズされた応答に使用できます。"

"イベントハンドラーではどのようなデータが利用できますか？"

"データを含むイベントはevent.detail.metadataに格納されます。例えば、onFHMessageSentにはメッセージ内容とタイムスタンプが含まれ、onFHMessageReceivedにはflow_id、message_id、メッセージテキストが含まれ、onFHFeedbackにはmessage_idとフィードバックが肯定的か否定的かの情報が含まれます。"

FlowHunt JS API：上級ユーザー向けインテグレーションガイド

FlowHunt JS API v2インテグレーションの完全リファレンス。チャットボットの埋め込み、全10イベントへのサブスクライブ、フロー変数の使用、URLパラメータによるインタラクション追跡、チャットウィンドウのプログラム制御の方法を解説します。

FlowHunt JavaScript API Chatbot Integration

FlowHunt JS APIは、チャットボットとウェブサイトの連携を完全に制御する機能を提供します。v2インテグレーションコードを使用すると、チャットボットの埋め込み、ライフサイクルおよびインタラクションイベントへのサブスクライブ、フロー変数による動的データの受け渡し、URLパラメータによるインタラクション追跡、チャットウィンドウのプログラム制御が可能です。

このガイドでは、JS APIのすべての側面を、コピーしてプロジェクトに適用できるコード例とともに解説します。

インテグレーションコード（v2）

FlowHuntでチャットボットを作成すると、インテグレーションスニペットが取得できます。HTMLの閉じタグ</body>の直前にコピーして貼り付けてください：

<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // The chatbot is ready — use chatbotManager here
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

YOUR_CHATBOT_IDとYOUR_WORKSPACE_IDをFlowHuntダッシュボードの値に置き換えてください。グローバル変数名（window.FHChatbot_YOUR_CHATBOT_ID）のチャットボットIDは、ハイフンの代わりにアンダースコアを使用します。

setConfig()による設定のオーバーライド

init()を呼び出す前に、setConfig()を使用してデフォルトのチャットボット設定をオーバーライドできます：

<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      headerTitle: 'Support Assistant',
      maxWindowWidth: '700px',
      showChatButton: false,
      flowVariables: {
        userId: '12345',
        plan: 'enterprise'
      },
      urlSuffix: '?utm_source=chatbot'
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // Chatbot initialized with custom config
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

利用可能な設定オプション

Option	Type	Description
`headerTitle`	string	カスタムヘッダータイトルテキスト
`maxWindowWidth`	string	チャットウィンドウの最大幅（例：`'700px'`）
`maxWindowHeight`	string	チャットウィンドウの最大高さ
`inputPlaceholder`	string	メッセージ入力欄のプレースホルダーテキスト
`showChatButton`	boolean	デフォルトのフローティングチャットボタンの表示・非表示
`openChatPanel`	boolean	ページ読み込み時にチャットパネルを自動的に開く
`flowVariables`	object	フローに渡されるカスタムデータのキーと値のペア
`urlSuffix`	string	チャットボットが生成するすべてのURLに追加されるクエリ文字列
`cookieConsent`	boolean	Cookieによるセッション永続化を有効にする
`embedded`	string	埋め込みモードを有効にする（閉じるボタンなし）
`theme`	string	テーマモード

フロー変数：動的データの受け渡し

フロー変数を使用すると、ウェブサイトからチャットボットフローにカスタムデータを送信できます。これにより、ユーザーのコンテキストに基づいたパーソナライズされた会話が可能になります。

window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
  flowVariables: {
    userId: getCurrentUserId(),
    userEmail: getCurrentUserEmail(),
    currentPage: window.location.pathname,
    plan: 'enterprise'
  }
});

設定すると、これらの変数はチャットボットのフローロジック内でアクセス可能になり、応答のパーソナライズ、会話のルーティング、AIエージェントへのコンテキスト渡しに使用できます。

URLサフィックス：チャットボットインタラクションの追跡

urlSuffixパラメータは、チャットボットが生成するすべてのURLにクエリ文字列を追加します。これは、分析ツールでチャットボット経由のトラフィックを追跡するのに便利です：

window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
  urlSuffix: '?utm_source=chatbot&utm_medium=widget'
});

ユースケース：

コンバージョン追跡 — Google Analyticsでチャットボットインタラクションからのコンバージョンを追跡。
ユーザー行動分析 — チャットボットとのやり取り後のユーザー行動を分析。
キャンペーン帰属 — チャットボットエンゲージメントを促進するキャンペーンの成果を帰属。

イベントリファレンス

FlowHunt JS APIは、windowオブジェクト上で10のカスタムイベントをディスパッチします。すべてのイベントはbubbles: trueとcomposed: trueを持つCustomEvent APIを使用します。

onFHChatbotReady

チャットボットウィジェットが完全にレンダリングされ、使用可能になったときに発火します。

イベントデータ： なし
発火タイミング： ウィジェットのDOMがマウントされ、チャットボタンが表示された後。

onFHChatbotSessionCreated

サーバー上で新しいチャットセッションが作成されたときに発火します。セッションが再起動されたときにも発火します。

イベントデータ： なし
発火タイミング： セッション作成APIコールが成功した後。

onFHChatbotWindowOpened

ユーザーがチャットウィンドウを開いたときに発火します。

イベントデータ： なし
発火タイミング： チャットパネルが表示されたとき。
注意： 埋め込みモードでは発火しません。

onFHChatbotWindowClosed

ユーザーがチャットウィンドウを閉じたときに発火します。

イベントデータ： なし
発火タイミング： チャットパネルが非表示になったとき。
注意： 埋め込みモードでは発火しません。

onFHMessageSent

ユーザーがメッセージを送信したときに発火します。

イベントデータ（event.detail.metadata）：

{
  "content": "Hello, I need help with...",
  "createdAt": "2026-02-19T10:30:00.000Z"
}

onFHMessageReceived

チャットボットが応答を受信して表示したときに発火します。

イベントデータ（event.detail.metadata）：

{
  "flow_id": "abc123",
  "message_id": "msg_456",
  "message": "Sure, I can help you with that!",
  "sender": {
    "sender_name": "Support Agent",
    "sender_avatar": "https://example.com/avatar.png"
  }
}

senderフィールドはオプションで、ヒューマンエージェントが関与している場合にのみ存在します。

onFHFormDataSent

ユーザーがチャットボットを通じてフォームデータを送信したときに発火します。

イベントデータ（event.detail.metadata）：

{
  "objectData": { "name": "John", "email": "john@example.com" },
  "createdAt": "2026-02-19T10:31:00.000Z"
}

onFHFeedback

ユーザーがチャットボットのメッセージに対して高評価または低評価のフィードバックを行ったときに発火します。

イベントデータ（event.detail.metadata）：

{
  "message_id": "msg_456",
  "content": "Optional feedback text",
  "feedback": "P"
}

feedbackの値は、肯定的（高評価）の場合は"P"、否定的（低評価）の場合は"N"です。

onFHToolCall

フロー処理中にツールまたはアクションが実行されたときに発火します。

イベントデータ（event.detail.metadata）：

{
  "metadata": {
    "flow_id": "abc123",
    "message_id": "msg_789",
    "message": "Calling search API..."
  },
  "createdAt": "2026-02-19T10:32:00.000Z"
}

注意： flowAssistantおよびflowAssistantV3モードでのみ発火し、標準チャットボットモードでは発火しません。

onFHError

チャットボットの動作中にエラーが発生したときに発火します。

イベントデータ（event.detail.metadata）：

{
  "metadata": {
    "flow_id": "abc123",
    "message_id": "msg_err",
    "message": "Flow execution failed"
  },
  "createdAt": "2026-02-19T10:33:00.000Z"
}

イベントへのサブスクライブ

チャットボットイベントにサブスクライブする方法は2つあります。

方法1：ウィンドウイベントリスナー

ページのどこでもwindow.addEventListenerを使用できます。これはチャットボットが読み込まれる前でも動作します：

<script>
document.addEventListener('DOMContentLoaded', function() {
  // Chatbot lifecycle events
  window.addEventListener('onFHChatbotReady', function(event) {
    console.log('Chatbot is ready');
  });

  window.addEventListener('onFHChatbotSessionCreated', function(event) {
    console.log('Session created');
  });

  window.addEventListener('onFHChatbotWindowOpened', function(event) {
    console.log('Chat window opened');
  });

  window.addEventListener('onFHChatbotWindowClosed', function(event) {
    console.log('Chat window closed');
  });

  // Message events
  window.addEventListener('onFHMessageSent', function(event) {
    console.log('User sent:', event.detail.metadata.content);
  });

  window.addEventListener('onFHMessageReceived', function(event) {
    console.log('Bot replied:', event.detail.metadata.message);
  });

  window.addEventListener('onFHFormDataSent', function(event) {
    console.log('Form submitted:', event.detail.metadata.objectData);
  });

  // Feedback
  window.addEventListener('onFHFeedback', function(event) {
    var feedback = event.detail.metadata;
    console.log('Feedback on message', feedback.message_id, ':',
      feedback.feedback);
  });

  // Tool calls (flowAssistant modes only)
  window.addEventListener('onFHToolCall', function(event) {
    console.log('Tool called:', event.detail.metadata);
  });

  // Errors
  window.addEventListener('onFHError', function(event) {
    console.error('Chatbot error:', event.detail.metadata);
  });
});
</script>

イベントのリッスンを停止するには、同じ関数参照を使ってremoveEventListenerを使用します：

var handleMessage = function(event) {
  console.log(event.detail.metadata);
};
window.addEventListener('onFHMessageReceived', handleMessage);

// Later, when you want to stop listening:
window.removeEventListener('onFHMessageReceived', handleMessage);

方法2：マネージャーコールバックメソッド

init()コールバック内で、チャットボットマネージャーの組み込みメソッドを使用します：

window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
  chatbotManager.onSessionCreated(function() {
    console.log('Session created');
  });

  chatbotManager.onWindowOpened(function() {
    console.log('Window opened');
  });

  chatbotManager.onWindowClosed(function() {
    console.log('Window closed');
  });

  chatbotManager.onMessageSent(function(event) {
    console.log('User sent:', event.metadata);
  });

  chatbotManager.onMessageReceived(function(event) {
    console.log('Bot replied:', event.metadata);
  });

  chatbotManager.onFormDataSent(function(event) {
    console.log('Form data:', event.metadata);
  });

  chatbotManager.onFeedback(function(event) {
    console.log('Feedback:', event.metadata);
  });

  chatbotManager.onToolCall(function(event) {
    console.log('Tool call:', event.metadata);
  });

  chatbotManager.onError(function(event) {
    console.error('Error:', event.metadata);
  });
});

マネージャーメソッドリファレンス

Method	Parameters	Description
`onSessionCreated(fn)`	`fn: () => void`	セッション作成をリッスン
`onWindowOpened(fn)`	`fn: () => void`	ウィンドウの開閉をリッスン
`onWindowClosed(fn)`	`fn: () => void`	ウィンドウの閉じをリッスン
`onMessageSent(fn)`	`fn: (event) => void`	ユーザーメッセージをリッスン
`onMessageReceived(fn)`	`fn: (event) => void`	ボットの応答をリッスン
`onFormDataSent(fn)`	`fn: (event) => void`	フォーム送信をリッスン
`onFeedback(fn)`	`fn: (event) => void`	ユーザーフィードバックをリッスン
`onToolCall(fn)`	`fn: (event) => void`	ツール実行をリッスン
`onError(fn)`	`fn: (event) => void`	エラーをリッスン
`openChat()`	—	チャットパネルを開く
`closeChat()`	—	チャットパネルを閉じる

カスタムチャット起動：ボタンの非表示とクリックで開く

チャットボットの表示タイミングを完全に制御するには、デフォルトのフローティングボタンを非表示にし、プログラムでチャットを開きます。例えば、独自のカスタムボタンから開くことができます。

完全な例

<!-- Your custom chat button -->
<button id="my-chat-button">Chat with us</button>

<!-- FlowHunt integration with hidden default button -->
<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      showChatButton: false
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // Open chat when your custom button is clicked
      document.getElementById('my-chat-button')
        .addEventListener('click', function() {
          chatbotManager.openChat();
        });
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

チャットボット準備完了時にのみカスタムボタンを表示

非表示起動とイベントリスナーを組み合わせて、高度なインタラクションを作成できます：

<button id="open-chat" style="display:none;">Need help?</button>

<script>
// Show a custom button only when the chatbot is ready
window.addEventListener('onFHChatbotReady', function() {
  document.getElementById('open-chat').style.display = 'block';
});
</script>

<!-- FlowHunt integration -->
<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      showChatButton: false
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      document.getElementById('open-chat')
        .addEventListener('click', function() {
          chatbotManager.openChat();
        });
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

完全なインテグレーション例

設定オーバーライド、イベント追跡、カスタムチャット起動を組み合わせた完全な動作例：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>FlowHunt Chatbot Integration</title>
</head>
<body>
  <h1>My Website</h1>
  <button id="open-chat-btn">Talk to our AI assistant</button>
  <button id="close-chat-btn">Close chat</button>

  <!-- Subscribe to events before the chatbot loads -->
  <script>
  document.addEventListener('DOMContentLoaded', function() {
    window.addEventListener('onFHChatbotReady', function() {
      console.log('Chatbot widget is ready');
    });

    window.addEventListener('onFHChatbotSessionCreated', function() {
      console.log('New chat session started');
    });

    window.addEventListener('onFHMessageSent', function(event) {
      console.log('User message:', event.detail.metadata.content);
    });

    window.addEventListener('onFHMessageReceived', function(event) {
      console.log('Bot response:', event.detail.metadata.message);
    });

    window.addEventListener('onFHFeedback', function(event) {
      var fb = event.detail.metadata;
      if (fb.feedback === 'P') {
        console.log('Positive feedback on message', fb.message_id);
      } else {
        console.log('Negative feedback on message', fb.message_id);
      }
    });

    window.addEventListener('onFHError', function(event) {
      console.error('Chatbot error:', event.detail.metadata);
    });
  });
  </script>

  <!-- FlowHunt integration -->
  <script id="fh-chatbot-script-YOUR_CHATBOT_ID">
    var currentScript = document.currentScript
      || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

    var script = document.createElement('script');
    script.async = true;
    script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
      + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

    script.onload = function() {
      window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
        showChatButton: false,
        headerTitle: 'AI Assistant',
        maxWindowWidth: '600px',
        flowVariables: {
          source: 'website',
          page: window.location.pathname
        },
        urlSuffix: '?utm_source=chatbot'
      });

      window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
        document.getElementById('open-chat-btn')
          .addEventListener('click', function() {
            chatbotManager.openChat();
          });

        document.getElementById('close-chat-btn')
          .addEventListener('click', function() {
            chatbotManager.closeChat();
          });
      });
    };

    if (currentScript && currentScript.parentNode) {
      currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
    } else {
      document.head.appendChild(script);
    }
  </script>
</body>
</html>

よくある質問

FlowHunt JS APIでリッスンできるイベントは何ですか？: FlowHunt JS APIは10のイベントを発行します：onFHChatbotReady、onFHChatbotSessionCreated、onFHChatbotWindowOpened、onFHChatbotWindowClosed、onFHMessageSent、onFHMessageReceived、onFHFormDataSent、onFHFeedback、onFHToolCall、onFHError。これらはwindow.addEventListenerまたはチャットボットマネージャーのコールバックメソッドを使用してサブスクライブできます。
デフォルトのチャットボタンを非表示にしてプログラムでチャットボットを開くには？: showChatButton: false設定オプションを使用してデフォルトボタンを非表示にし、chatbotManager.openChat()を呼び出して任意のタイミングでチャットボットを開きます。例えば、カスタムボタンのクリック時に開くことができます。
マネージャーコールバックメソッドとwindow.addEventListenerの違いは何ですか？: どちらの方法も使用できます。マネージャーコールバックメソッド（例：chatbotManager.onMessageSent(fn)）はinitコールバック内で呼び出され、マネージャーインスタンスに紐づけられます。window.addEventListenerアプローチ（例：window.addEventListener('onFHMessageSent', fn)）は、チャットボットの読み込み前でも、ページのどこにでも設定できます。
フロー変数を使用してチャットボットにカスタムデータを渡すには？: setConfig()のflowVariables設定オプションを使用して、ユーザーID、メールアドレス、ページURLなどのキーと値のペアを渡します。これらの変数はチャットボットフロー内で利用可能になり、パーソナライズされた応答に使用できます。
イベントハンドラーではどのようなデータが利用できますか？: データを含むイベントはevent.detail.metadataに格納されます。例えば、onFHMessageSentにはメッセージ内容とタイムスタンプが含まれ、onFHMessageReceivedにはflow_id、message_id、メッセージテキストが含まれ、onFHFeedbackにはmessage_idとフィードバックが肯定的か否定的かの情報が含まれます。