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	쿠키를 통한 세션 지속성 활성화
`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는 10개의 이벤트를 발생시킵니다: onFHChatbotReady, onFHChatbotSessionCreated, onFHChatbotWindowOpened, onFHChatbotWindowClosed, onFHMessageSent, onFHMessageReceived, onFHFormDataSent, onFHFeedback, onFHToolCall, onFHError. window.addEventListener 또는 챗봇 매니저 콜백 메서드를 사용하여 구독할 수 있습니다.
: showChatButton: false 설정 옵션을 사용하여 기본 버튼을 숨긴 다음, chatbotManager.openChat()을 호출하여 원하는 시점에 챗봇을 엽니다. 예를 들어, 커스텀 버튼 클릭 시 열 수 있습니다.
: 두 가지 방법 모두 사용할 수 있습니다. 매니저 콜백 메서드(예: 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와 피드백이 긍정적인지 부정적인지에 대한 정보가 포함됩니다.