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

订阅事件

有两种方式可以订阅聊天机器人事件。

方法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以及反馈是正面还是负面的信息。