제품 가이드

웹사이트 임베드

요약

스튜디오에서 만든 챗봇의 공개 페이지를 외부 웹사이트에 임베드하는 방법을 안내합니다. 간단한 위젯 스크립트 방식과, 직접 iframe을 제어하는 방식 두 가지를 지원하며, 부모 페이지와 챗봇 간 postMessage 통신도 가능합니다.

사전 준비

임베드를 시작하기 전에 공개 페이지 URL이 필요합니다.

스튜디오에서 챗봇을 만든 뒤 공유 옵션을 켭니다.
발급된 공개 페이지 URL을 확인합니다. 형식은 다음과 같습니다.


text
https://<서브도메인>.factchat.bot/public/chatbots/<챗봇-식별자>

공개 옵션을 켜면 공개/비공개 여부와 상관없이 누구나 URL을 통해 챗봇을 사용할 수 있습니다. 임베드되는 챗봇이 사용한 크레딧은 챗봇 소유자의 한도에서 차감됩니다.

방법 1. 위젯 스크립트 (플로팅 버튼)

가장 간단한 방법입니다. 아래 스크립트를 웹사이트의 <head> 태그 바로 아래에 붙여넣으면, 모든 페이지 우측 하단에 챗 버튼이 표시되고 클릭 시 챗봇이 열립니다.


html
<script src="https://plugin.factchat.bot/latest/plugin.min.js"></script>
<script>
  window.ChatWidgetConfig = {
    chatUrl: 'https://<서브도메인>.factchat.bot/public/chatbots/<챗봇-식별자>',
    position: { bottom: 20, right: 20 },
    buttonColor: '#1751D0',
    title: 'Chat with us',
  };
</script>

설정 옵션

window.ChatWidgetConfig에 전달할 수 있는 옵션입니다.

옵션	타입	기본값	설명
`chatUrl`	`string`	필수	공개 페이지 URL
`position`	`object`	`{ bottom: 20, right: 20 }`	버튼/창의 위치(px). `top` `right` `bottom` `left` 사용
`buttonColor`	`string`	`"#007bff"`	버튼 색상 (hover 색은 자동으로 밝아짐)
`buttonSize`	`string`	`"60px"`	버튼 크기 (CSS 단위)
`buttonText`	`string`	`"💬"`	버튼 텍스트 또는 이모지 (`customImage` 설정 시 무시)
`customImage`	`string`	-	버튼으로 사용할 커스텀 이미지 URL
`title`	`string`	`"Chat with us"`	위젯 제목
`iframeWidth`	`string`	`"375px"`	채팅 iframe 너비
`iframeHeight`	`string`	`"607px"`	채팅 iframe 높이
`zIndex`	`number`	`9999`	CSS z-index 값
`enabled`	`boolean`	`true`	위젯 활성화 여부
`showOnMobile`	`boolean`	`true`	모바일에서 표시 여부
`autoOpen`	`boolean`	`false`	페이지 로드 시 자동 열기
`openDelay`	`number`	`0`	자동 열기 지연 시간 (ms)

스크립트 태그에 data-chat-url, data-button-color, data-position-bottom 등의 data-* 속성으로도 동일하게 설정할 수 있습니다.

방법 2. iframe 직접 삽입

위젯의 플로팅 버튼 대신, 페이지의 원하는 위치에 직접 iframe을 배치하고 열고 닫는 동작을 직접 제어하고 싶다면 이 방법을 사용합니다.

공개 페이지 URL 뒤에 ?widget=true 파라미터를 붙이면 위젯 모드로 렌더링되어 테넌트 로고와 배지가 숨겨지고, 우측 상단에 새 채팅 버튼과 닫기(X) 버튼만 표시됩니다.


html
<iframe
  id="factchat-widget"
  src="https://<서브도메인>.factchat.bot/public/chatbots/<챗봇-식별자>?widget=true"
  style="border: 0; width: 400px; height: 600px;"
  title="FactChat"
></iframe>

URL 파라미터

파라미터	값	설명
`widget`	`true` / `false`	위젯 모드 활성화. 로고/배지를 숨기고 닫기 버튼을 노출합니다
`closeButton`	`false`	닫기(X) 버튼을 숨깁니다. 직접 만든 버튼으로 제어할 때 사용

부모 페이지 ↔ 챗봇 통신 (postMessage)

임베드된 챗봇은 주요 동작이 발생할 때 부모 창으로 postMessage를 전송합니다. 부모 페이지에서 message 이벤트를 수신하여 iframe의 표시 상태를 직접 제어할 수 있습니다.

챗봇이 보내는 이벤트

`type`	추가 데이터	설명
`ready`	-	챗봇 로드 완료
`resize`	`width`, `height`	챗봇 창 크기 변경 요청
`close`	-	사용자가 닫기(X) 버튼을 누름
`error`	`message`	오류 발생

부모 페이지에서 수신하기

아래는 챗봇의 닫기(X) 버튼으로 iframe을 숨기는 예제입니다.


html
<iframe
  id="factchat-widget"
  src="https://<서브도메인>.factchat.bot/public/chatbots/<챗봇-식별자>?widget=true"
  style="border: 0; width: 400px; height: 600px;"
  title="FactChat"
></iframe>

<script>
  window.addEventListener('message', function (event) {
    // 보안: 신뢰하는 origin만 허용하세요
    if (event.origin !== 'https://<서브도메인>.factchat.bot') return;

    if (event.data && event.data.type === 'close') {
      // iframe 또는 부모 래퍼 요소의 display를 제어
      document.getElementById('factchat-widget').style.display = 'none';
    }
  });
</script>

message 이벤트를 수신할 때는 반드시 event.origin을 공개 페이지의 도메인과 비교하여 검증하세요. 검증 없이 메시지를 신뢰하면 다른 사이트가 보낸 메시지에도 반응할 수 있습니다.

방법 1의 위젯 스크립트는 이 postMessage 통신을 내부적으로 처리하므로, 직접 이벤트를 수신할 필요는 없습니다. iframe을 직접 삽입한 경우에만 위와 같이 부모 페이지에서 처리하면 됩니다.

마지막 수정 날짜: Jun 04, 2026

Univ-in-Data

음성 대화