FlowHunt JS API: Hướng dẫn tích hợp dành cho người dùng nâng cao

Tài liệu tham khảo đầy đủ về tích hợp FlowHunt JS API v2. Tìm hiểu cách nhúng chatbot, đăng ký tất cả 10 sự kiện, sử dụng biến flow, theo dõi tương tác bằng tham số URL và điều khiển cửa sổ chat theo chương trình.

FlowHunt JavaScript API Chatbot Integration

FlowHunt JS API cho phép bạn kiểm soát hoàn toàn cách chatbot tích hợp với trang web của bạn. Sử dụng mã tích hợp v2, bạn có thể nhúng chatbot, đăng ký các sự kiện vòng đời và tương tác, truyền dữ liệu động qua biến flow, theo dõi tương tác bằng tham số URL và điều khiển cửa sổ chat theo chương trình.

Hướng dẫn này bao gồm mọi khía cạnh của JS API với các ví dụ mã mà bạn có thể sao chép và điều chỉnh cho dự án của mình.

Mã tích hợp (v2)

Khi bạn tạo chatbot trong FlowHunt, bạn sẽ nhận được đoạn mã tích hợp. Sao chép và dán nó vào HTML ngay trước thẻ đóng </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>

Thay thế YOUR_CHATBOT_ID và YOUR_WORKSPACE_ID bằng các giá trị từ bảng điều khiển FlowHunt. ID chatbot trong tên biến toàn cục (window.FHChatbot_YOUR_CHATBOT_ID) sử dụng dấu gạch dưới thay vì dấu gạch ngang.

Ghi đè cấu hình với setConfig()

Trước khi gọi init(), bạn có thể ghi đè các cài đặt chatbot mặc định bằng 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>

Các tùy chọn cấu hình có sẵn

OptionTypeDescription
headerTitlestringVăn bản tiêu đề header tùy chỉnh
maxWindowWidthstringChiều rộng tối đa của cửa sổ chat (ví dụ: '700px')
maxWindowHeightstringChiều cao tối đa của cửa sổ chat
inputPlaceholderstringVăn bản placeholder cho ô nhập tin nhắn
showChatButtonbooleanHiển thị hoặc ẩn nút chat nổi mặc định
openChatPanelbooleanTự động mở bảng chat khi tải trang
flowVariablesobjectCác cặp khóa-giá trị dữ liệu tùy chỉnh được truyền cho flow
urlSuffixstringChuỗi truy vấn được thêm vào tất cả URL do chatbot tạo ra
cookieConsentbooleanBật tính năng duy trì phiên qua cookie
embeddedstringBật chế độ nhúng (không có nút đóng)
themestringChế độ giao diện
Logo

Sẵn sàng phát triển doanh nghiệp của bạn?

Bắt đầu dùng thử miễn phí ngay hôm nay và xem kết quả trong vài ngày.

Yêu cầu demo Đăng nhập

Biến flow: Truyền dữ liệu động

Biến flow cho phép bạn gửi dữ liệu tùy chỉnh từ trang web vào flow chatbot. Điều này cho phép tạo các cuộc hội thoại được cá nhân hóa dựa trên ngữ cảnh người dùng.

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

Sau khi thiết lập, các biến này có thể truy cập được trong logic flow chatbot, cho phép bạn cá nhân hóa phản hồi, định tuyến cuộc hội thoại hoặc truyền ngữ cảnh cho các AI agent.

Hậu tố URL: Theo dõi tương tác chatbot

Tham số urlSuffix thêm chuỗi truy vấn vào mọi URL do chatbot tạo ra. Điều này hữu ích để theo dõi lưu lượng truy cập từ chatbot trong các công cụ phân tích:

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

Các trường hợp sử dụng:

  • Theo dõi chuyển đổi từ các tương tác chatbot trong Google Analytics.
  • Phân tích hành vi người dùng sau khi tương tác với chatbot.
  • Gán chiến dịch thúc đẩy sự tham gia của chatbot.

Tham chiếu sự kiện

FlowHunt JS API phát 10 sự kiện tùy chỉnh trên đối tượng window. Tất cả sự kiện sử dụng CustomEvent API với bubbles: true và composed: true.

onFHChatbotReady

Được kích hoạt khi widget chatbot đã được render hoàn toàn và sẵn sàng sử dụng.

  • Dữ liệu sự kiện: Không có
  • Thời điểm: Sau khi DOM widget được mount và nút chat hiển thị.

onFHChatbotSessionCreated

Được kích hoạt khi phiên chat mới được tạo trên máy chủ. Cũng được kích hoạt khi phiên được khởi động lại.

  • Dữ liệu sự kiện: Không có
  • Thời điểm: Sau khi cuộc gọi API tạo phiên thành công.

onFHChatbotWindowOpened

Được kích hoạt khi người dùng mở cửa sổ chat.

  • Dữ liệu sự kiện: Không có
  • Thời điểm: Khi bảng chat trở nên hiển thị.
  • Lưu ý: Không được kích hoạt trong chế độ nhúng.

onFHChatbotWindowClosed

Được kích hoạt khi người dùng đóng cửa sổ chat.

  • Dữ liệu sự kiện: Không có
  • Thời điểm: Khi bảng chat bị ẩn.
  • Lưu ý: Không được kích hoạt trong chế độ nhúng.

onFHMessageSent

Được kích hoạt khi người dùng gửi tin nhắn.

  • Dữ liệu sự kiện (event.detail.metadata):
{
  "content": "Hello, I need help with...",
  "createdAt": "2026-02-19T10:30:00.000Z"
}

onFHMessageReceived

Được kích hoạt khi chatbot nhận và hiển thị phản hồi.

  • Dữ liệu sự kiện (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"
  }
}

Trường sender là tùy chọn và chỉ xuất hiện khi có nhân viên hỗ trợ tham gia.

onFHFormDataSent

Được kích hoạt khi người dùng gửi dữ liệu biểu mẫu qua chatbot.

  • Dữ liệu sự kiện (event.detail.metadata):
{
  "objectData": { "name": "John", "email": "john@example.com" },
  "createdAt": "2026-02-19T10:31:00.000Z"
}

onFHFeedback

Được kích hoạt khi người dùng đánh giá tích cực hoặc tiêu cực cho tin nhắn của chatbot.

  • Dữ liệu sự kiện (event.detail.metadata):
{
  "message_id": "msg_456",
  "content": "Optional feedback text",
  "feedback": "P"
}

Giá trị feedback là "P" cho tích cực (thích) hoặc "N" cho tiêu cực (không thích).

onFHToolCall

Được kích hoạt khi một công cụ hoặc hành động được thực thi trong quá trình xử lý flow.

  • Dữ liệu sự kiện (event.detail.metadata):
{
  "metadata": {
    "flow_id": "abc123",
    "message_id": "msg_789",
    "message": "Calling search API..."
  },
  "createdAt": "2026-02-19T10:32:00.000Z"
}

Lưu ý: Chỉ được kích hoạt trong chế độ flowAssistant và flowAssistantV3, không kích hoạt trong chế độ chatbot tiêu chuẩn.

onFHError

Được kích hoạt khi xảy ra lỗi trong quá trình hoạt động của chatbot.

  • Dữ liệu sự kiện (event.detail.metadata):
{
  "metadata": {
    "flow_id": "abc123",
    "message_id": "msg_err",
    "message": "Flow execution failed"
  },
  "createdAt": "2026-02-19T10:33:00.000Z"
}

Đăng ký sự kiện

Có hai cách để đăng ký các sự kiện chatbot.

Cách 1: Trình lắng nghe sự kiện Window

Sử dụng window.addEventListener ở bất kỳ đâu trong trang. Cách này hoạt động ngay cả trước khi chatbot được tải:

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

Để ngừng lắng nghe sự kiện, sử dụng removeEventListener với cùng tham chiếu hàm:

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

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

Cách 2: Phương thức callback của trình quản lý

Bên trong callback init(), sử dụng các phương thức tích hợp của trình quản lý chatbot:

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);
  });
});

Tham chiếu phương thức trình quản lý

MethodParametersDescription
onSessionCreated(fn)fn: () => voidLắng nghe sự kiện tạo phiên
onWindowOpened(fn)fn: () => voidLắng nghe sự kiện mở cửa sổ
onWindowClosed(fn)fn: () => voidLắng nghe sự kiện đóng cửa sổ
onMessageSent(fn)fn: (event) => voidLắng nghe tin nhắn của người dùng
onMessageReceived(fn)fn: (event) => voidLắng nghe phản hồi của bot
onFormDataSent(fn)fn: (event) => voidLắng nghe gửi biểu mẫu
onFeedback(fn)fn: (event) => voidLắng nghe phản hồi của người dùng
onToolCall(fn)fn: (event) => voidLắng nghe thực thi công cụ
onError(fn)fn: (event) => voidLắng nghe lỗi
openChat()—Mở bảng chat
closeChat()—Đóng bảng chat

Kích hoạt chat tùy chỉnh: Ẩn nút và mở khi nhấp

Để kiểm soát hoàn toàn thời điểm chatbot xuất hiện, hãy ẩn nút nổi mặc định và mở chat theo chương trình — ví dụ, từ nút tùy chỉnh của bạn.

Ví dụ đầy đủ

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

Chỉ hiển thị nút tùy chỉnh khi chatbot đã sẵn sàng

Bạn có thể kết hợp kích hoạt ẩn với trình lắng nghe sự kiện để tạo các tương tác nâng cao:

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

Ví dụ tích hợp hoàn chỉnh

Một ví dụ hoạt động đầy đủ minh họa việc ghi đè cấu hình, theo dõi sự kiện và kích hoạt chat tùy chỉnh kết hợp với nhau:

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

Câu hỏi thường gặp

Tôi có thể lắng nghe những sự kiện nào với FlowHunt JS API?

FlowHunt JS API phát ra 10 sự kiện: onFHChatbotReady, onFHChatbotSessionCreated, onFHChatbotWindowOpened, onFHChatbotWindowClosed, onFHMessageSent, onFHMessageReceived, onFHFormDataSent, onFHFeedback, onFHToolCall và onFHError. Bạn có thể đăng ký các sự kiện này bằng window.addEventListener hoặc thông qua các phương thức callback của trình quản lý chatbot.

Làm thế nào để ẩn nút chat mặc định và mở chatbot theo chương trình?

Sử dụng tùy chọn cấu hình showChatButton: false để ẩn nút mặc định, sau đó gọi chatbotManager.openChat() để mở chatbot theo ý bạn — ví dụ, khi nhấp vào nút tùy chỉnh.

Sự khác biệt giữa phương thức callback của trình quản lý và window.addEventListener là gì?

Cả hai cách đều hoạt động. Các phương thức callback của trình quản lý (ví dụ: chatbotManager.onMessageSent(fn)) được gọi bên trong callback init và gắn với thể hiện trình quản lý. Cách tiếp cận window.addEventListener (ví dụ: window.addEventListener('onFHMessageSent', fn)) có thể được thiết lập ở bất kỳ đâu trong trang, ngay cả trước khi chatbot tải xong.

Làm thế nào để truyền dữ liệu tùy chỉnh cho chatbot bằng biến flow?

Sử dụng tùy chọn cấu hình flowVariables trong setConfig() để truyền các cặp khóa-giá trị như ID người dùng, email hoặc URL trang. Các biến này sẽ có sẵn bên trong flow chatbot của bạn để tạo phản hồi được cá nhân hóa.

Những dữ liệu nào có sẵn trong trình xử lý sự kiện?

Các sự kiện mang dữ liệu sẽ chứa dữ liệu trong event.detail.metadata. Ví dụ, onFHMessageSent bao gồm nội dung tin nhắn và dấu thời gian, onFHMessageReceived bao gồm flow_id, message_id và nội dung tin nhắn, và onFHFeedback bao gồm message_id cùng thông tin phản hồi là tích cực hay tiêu cực.