챗봇

조직 웹사이트에 Keural 챗봇을 넣습니다. 방문자가 화면 구석의 버튼을 누르면 챗봇 창이 열립니다. 관리 화면에서 만든 설치 코드를 웹사이트에 붙여 넣어 설치합니다.

챗봇 만들기링크 복사

1. 조직 소유자·관리자가 조직 관리 → 챗봇 관리에서 챗봇 추가를 누릅니다.
2. 챗봇 이름과 기본 도메인(예: https://example.com)을 입력해 등록합니다.
3. 챗봇을 열어 세 탭을 설정합니다.

4. 설치 코드를 웹사이트에 붙여 넣습니다.

설치 코드링크 복사

토큰·설치코드 탭에서 HTML용 또는 Next.js용 코드를 복사합니다. 코드는 두 부분으로 구성됩니다.

• 로더: Keural 함수를 만들고, 페이지 로드가 끝나면 챗봇 스크립트(/plugin/keural-widget@1.0.1.js)를 비동기로 불러옵니다. 스크립트 로드 전에 호출한 명령은 대기열에 쌓였다가 순서대로 실행됩니다.
• 시작 명령: Keural('boot', { token: '…' }). 토큰은 wgt_로 시작합니다.

스크립트 버전은 주소에 고정되어 있습니다. 새 버전이 나오면 설치 코드를 다시 복사해 교체합니다. 같은 페이지에 설치 코드를 두 번 넣으면 두 번째 코드는 무시되고 콘솔에 오류가 기록됩니다.

<script id="keural-one-script">
  /* 토큰·설치코드 탭에서 복사한 코드 */
</script>

Next.js에서는 next/script의 <Script id="keural-one-script" strategy="afterInteractive">로 넣습니다. 모든 페이지에 표시하려면 루트 레이아웃에 넣습니다.

시작 옵션링크 복사

boot에 넣은 값은 관리 화면 설정보다 우선합니다. 페이지별로 모양을 바꿀 때 씁니다.

Keural('boot', {
  token: 'wgt_…',
  theme: 'system',
  header: { enabled: true, extended: true, draggable: true, title: '고객 지원', color: '#495BD8' },
  button: { visible: true, iconUrl: 'https://example.com/icon.png', color: '#495BD8', position: 'right', offsetX: 30, offsetY: 30 },
});

새로 만든 챗봇의 기본값은 헤더 노출·확장 켬, 헤더·버튼 색 #495BD8, 오른쪽, 오프셋 30px, 테마 system입니다.

페이지 제어링크 복사

Keural.open() 같은 메서드는 스크립트 로드 후에만 동작합니다. 페이지 로드 직후 호출할 때는 Keural('open')처럼 함수 형태로 호출하면 순서대로 실행됩니다.

<button onclick="Keural('open')">상담하기</button>

기본 버튼을 숨기고(button.visible: false) 페이지의 버튼으로 열 수도 있습니다.

화면 크기링크 복사

챗봇 창은 390×800px이며, 화면 너비가 480px 이하면 전체 화면으로 열립니다. 헤더의 크게 보기 버튼으로 창을 키웁니다.

표시 도메인링크 복사

• 챗봇은 기본 도메인과 호스트가 같은 페이지에서 열립니다. 호스트는 포트까지 비교하며 대소문자는 구분하지 않습니다. www.가 붙은 주소와 하위 도메인은 다른 호스트입니다. 개발 서버에서 시험하려면 그 주소를 기본 도메인으로 하는 챗봇을 따로 만듭니다.
• 기본 도메인은 만든 뒤 바꿀 수 없습니다. 바꾸려면 챗봇을 새로 만듭니다.
• 고급 설정의 허용 도메인을 비우면 기본 도메인의 모든 페이지에서 열립니다. 허용 도메인을 넣으면 그 주소로 시작하는 페이지에서만 열립니다. https://example.com/help처럼 경로까지 입력하면 그 아래 페이지로 범위가 좁혀집니다. 허용 도메인은 http:// 또는 https://로 시작하며 최대 5개입니다.
• 설치 코드의 토큰은 페이지에 노출됩니다. 챗봇에는 공개해도 되는 내용만 연결합니다.

보안 정책(CSP)링크 복사

사이트에 Content-Security-Policy를 적용했으면 다음을 허용합니다. 주소는 keural.ai 기준입니다.