Options

초기화 시 사용할 수 있는 모든 옵션을 설명합니다.

applicationKey

Type: string
Required: Yes
Default: -

애플리케이션 인증 키입니다. MSAP 관리자로부터 발급받습니다.

javascript

MSAPChat.init({
  applicationKey: 'your-application-key', 
});

WARNING

applicationKey는 필수 값입니다. 없으면 위젯이 작동하지 않습니다.

mode

Type: 'inline' | 'popup'
Required: No
Default: 'inline'

위젯의 표시 모드를 지정합니다.

javascript

MSAPChat.init({
  applicationKey: 'your-key',
  mode: 'popup', 
});

inline 모드 (기본값)

페이지 내부에 임베드되는 토글 가능한 위젯입니다.

특징:

페이지 내부에 통합
모바일에서 완벽 지원
팝업 차단 이슈 없음
페이지 전환 시 대화 초기화됨

별도의 브라우저 창으로 열리는 위젯입니다.

특징:

별도 브라우저 창으로 분리
SSR 환경에서 페이지 전환 시에도 대화 유지
멀티태스킹 지원 (웹사이트 탐색하면서 채팅)
모바일에서는 자동으로 inline 모드로 전환
토글 버튼으로 팝업 열기/닫기 가능

사용 시나리오:

Next.js/Nuxt.js 등 SSR 프로젝트
페이지 전환이 빈번한 웹사이트
대형 화면에서 넓은 채팅 공간 필요

INFO

모바일 기기에서 popup 모드는 자동으로 inline 모드로 전환됩니다.

containerId

Type: string
Required: No
Default: 자동 생성
Mode: inline 모드 전용

위젯이 렌더링될 컨테이너의 DOM ID입니다.

javascript

MSAPChat.init({
  applicationKey: 'your-key',
  mode: 'inline',
  containerId: 'my-chat-widget', 
});

미지정 시 SDK가 자동으로 컨테이너를 생성합니다.

WARNING

containerId는 inline 모드에서만 사용됩니다. popup 모드에서는 무시됩니다.

커스텀 컨테이너 사용

html

<!-- 커스텀 컨테이너 -->
<div id="my-chat-widget"></div>

<script>
  MSAPChat.init({
    applicationKey: 'your-key',
    containerId: 'my-chat-widget',
  });
</script>

iframeSrc

Type: string
Required: No
Default: 자동 해석 (아래 우선순위 참고)

위젯 iframe이 가리킬 chat 위젯 origin입니다. 사내/폐쇄망에 배포하는 경우 이 값으로 내부 chat 호스트를 지정합니다.

javascript

MSAPChat.init({
  applicationKey: 'your-key',
  iframeSrc: 'https://chat.내부도메인', 
});

해석 우선순위

iframeSrc를 명시하지 않으면 SDK가 런타임에 다음 순서로 위젯 origin을 결정합니다.

init({ iframeSrc }) — 명시 값 (최우선)
window.MSAP_CHAT_IFRAME_SRC — 스크립트 로드 전 설정한 전역 값
SDK 스크립트 origin 자동 유추 — SDK와 위젯이 같은 호스트일 때
레거시 기본값 https://ai-chat.turacocloud.com

사설 네트워크

내부 호스팅·폐쇄망 구성은 사설 네트워크 / 내부 호스팅 문서를 참고하세요.

width

Type: number
Required: No
Default: 400

위젯의 너비를 픽셀 단위로 지정합니다.

javascript

MSAPChat.init({
  applicationKey: 'your-key',
  width: 500, 
});

모드별 동작:

inline 모드: 최소 400px, 더 작은 값은 자동으로 400px로 조정
popup 모드: 제한 없음, 지정한 값 그대로 적용

height

Type: number
Required: No
Default: 640

위젯의 높이를 픽셀 단위로 지정합니다.

javascript

MSAPChat.init({
  applicationKey: 'your-key',
  height: 700, 
});

모드별 동작:

inline 모드: 최소 640px, 더 작은 값은 자동으로 640px로 조정
popup 모드: 제한 없음, 지정한 값 그대로 적용

showToggleButton

Type: boolean
Required: No
Default: true

화면 우측 하단에 표시되는 토글 버튼의 표시 여부를 지정합니다.

javascript

MSAPChat.init({
  applicationKey: 'your-key',
  showToggleButton: false, 
});

동작:

true (기본값): 토글 버튼 표시
- inline 모드: 클릭 시 위젯 열기/닫기
- popup 모드: 클릭 시 팝업 창 열기/닫기
false: 토글 버튼 숨김, 프로그래밍 방식으로만 제어 가능

TIP

토글 버튼을 숨기면 open(), close(), toggle() 메서드를 사용하여 위젯을 제어해야 합니다.

theme

Type: 'light' | 'dark'
Required: No
Default: 'light'

위젯의 색 테마를 지정합니다. 호스트 페이지가 다크 모드를 지원한다면 페이지의 현재 테마를 넘겨 위젯이 같은 톤으로 보이게 할 수 있습니다.

javascript

MSAPChat.init({
  applicationKey: 'your-key',
  theme: 'dark', 
});

동작:

지정한 값은 iframe URL 쿼리(?theme=)와 초기화 메시지 양쪽으로 전달됩니다. 덕분에 위젯이 뜨는 첫 화면부터 해당 테마로 그려집니다.
초기화 이후 테마를 바꾸려면 setTheme() 메서드를 사용합니다. 위젯을 다시 마운트하지 않고 바뀝니다.

javascript

const widget = MSAPChat.init({ applicationKey: 'your-key' });

// 호스트 페이지 테마가 바뀔 때
widget.setTheme('dark');

TIP

호스트 페이지가 OS 설정(prefers-color-scheme)을 따른다면, 초기값과 변경 시점 모두 그 값을 그대로 넘기면 됩니다.

완전한 예제

Inline 모드 예제

javascript

const widget = MSAPChat.init({
  applicationKey: 'your-application-key',
  mode: 'inline',
  containerId: 'custom-container',
  width: 500,
  height: 700,
  showToggleButton: true,
  theme: 'light',
});

javascript

const widget = MSAPChat.init({
  applicationKey: 'your-application-key',
  mode: 'popup',
  width: 400,
  height: 640,
  showToggleButton: true,
});

TypeScript 인터페이스

SDK 타입 파일을 포함하면 MSAPChat.Options를 전역에서 사용할 수 있습니다. 타입 파일 설치 방법은 TypeScript 타입 안내를 참고하세요. 실제 인터페이스는 다음과 같습니다.

typescript

declare namespace MSAPChat {
  interface Options {
    applicationKey: string; // Required
    mode?: 'inline' | 'popup'; // Optional (default: 'inline')
    containerId?: string; // Optional (inline 모드 전용)
    iframeSrc?: string; // Optional
    width?: number; // Optional (default: 400)
    height?: number; // Optional (default: 640)
    showToggleButton?: boolean; // Optional (default: true)
    theme?: 'light' | 'dark'; // Optional (default: 'light')
  }
}

다음 단계

Initialization - 초기화 방법
Security - 보안 정보
Methods - API 메서드

Options ​

applicationKey ​

mode ​

inline 모드 (기본값) ​

popup 모드 ​

containerId ​

커스텀 컨테이너 사용 ​

iframeSrc ​

해석 우선순위 ​

width ​

height ​

showToggleButton ​

theme ​

완전한 예제 ​

Inline 모드 예제 ​

Popup 모드 예제 ​

TypeScript 인터페이스 ​

다음 단계 ​

Options

applicationKey

mode

inline 모드 (기본값)

popup 모드

containerId

커스텀 컨테이너 사용

iframeSrc

해석 우선순위

width

height

showToggleButton

theme

완전한 예제

Inline 모드 예제

Popup 모드 예제

TypeScript 인터페이스

다음 단계