커스터마이징

ZeroTalk.init() 에 옵션을 전달해 위젯 외관과 동작을 조정합니다.

ZeroTalk.init({
  pluginKey: "YOUR_PLUGIN_KEY",
  apiBaseUrl: "https://api.talk.zeroworks.ai/api/v1",
  wsUrl: "wss://api.talk.zeroworks.ai/ws/sdk",
  title: "고객센터",
  hideLauncher: false,
  hideGreeting: false,
  launcherSize: "medium",
  position: { bottom: 20, right: 20 },
  greeting: {
    text: "안녕하세요! 무엇을 도와드릴까요?",
    delay: 3000,
  },
  border: {
    window: "#E0E0E0",
  },
});

옵션

옵션	타입	기본값	설명
`pluginKey`	string	(필수)	Plugin Key
`title`	string	—	위젯 헤더 타이틀
`hideLauncher`	boolean	`false`	런처 버튼 숨기기
`hideGreeting`	boolean	`false`	인사 메시지 숨기기
`launcherSize`	`"small"` \| `"medium"` \| `"large"` \| number	`"medium"`	런처 크기
`position`	`{ bottom, right }`	`{ bottom: 20, right: 20 }`	위젯 위치 (px)
`launcherIcon`	string	—	커스텀 런처 아이콘 (SVG)
`autoStart`	boolean	`true`	자동 연결
`keepChannel`	boolean	`false`	채널 이탈 후에도 채널 유지
`greeting.text`	string	—	인사 메시지 텍스트
`greeting.delay`	number	—	인사 메시지 지연 시간 (ms)
`greeting.onlineText`	string	—	온라인 상태 텍스트
`greeting.offlineText`	string	—	오프라인 상태 텍스트
`border.window`	string \| `{ color, width }`	—	채팅 창 테두리
`border.launcher`	string \| `{ color, width }`	—	런처 버튼 테두리
`border.greeting`	string \| `{ color, width }`	—	인사 말풍선 테두리
`greeting.hideStatus`	boolean	`false`	인사 말풍선의 온라인/오프라인 상태 표시 숨김
`greeting.dismissOnClick`	boolean	`true`	인사 말풍선을 클릭하면 페이지 세션 동안 닫힘
`language`	`"auto"` \| `"ko"` \| `"en"` \| `"zh-CN"` \| `"zh-TW"` \| `"ja"`	`"auto"`	위젯 UI 언어. `"auto"` 는 브라우저 언어를 따름
`theme`	`Partial<ThemeTokens>`	—	색상·여백 등 CSS 변수 토큰 오버라이드
`locale`	`Partial<WidgetLocale>`	—	개별 문구 로컬라이즈 (예: 입력창 placeholder)
`sound`	`{ url, playWhen? }`	—	새 메시지 알림음. `playWhen` 은 `"always"` 또는 `"whenClosed"` (기본 `"whenClosed"`)
`showUnreadBadge`	boolean	`false`	미읽음 메시지가 있을 때 런처에 빨간 점 표시
`onUnreadChange`	`(count: number) => void`	—	미읽음 수 변경 콜백
`enablePageTracking`	boolean	`false`	SPA 라우트 변경 시 page_view 이벤트 전송. 활성화 시 모든 방문자에 contact 가 생성되므로 KPI · 과금 영향을 검토한 뒤 켜세요

테두리 설정

채팅 창, 런처 버튼, 인사 말풍선에 각각 독립적으로 테두리를 적용할 수 있습니다. 색상만 지정하면 두께는 1px이 기본값이며, 두께를 바꾸려면 객체로 전달합니다.

ZeroTalk.init({
  pluginKey: "YOUR_PLUGIN_KEY",
  apiBaseUrl: "https://api.talk.zeroworks.ai/api/v1",
  wsUrl: "wss://api.talk.zeroworks.ai/ws/sdk",
  border: {
    window: "#E0E0E0",                        // 1px (기본)
    launcher: { color: "#4589FF", width: 2 }, // 2px
    greeting: { color: "#E0E0E0", width: 3 }, // 3px
  },
});

각 속성은 생략 가능하며, 생략 시 테두리가 표시되지 않습니다.

사용자 정보 연동

로그인된 사용자 정보를 함께 전달할 수 있습니다. memberHash 발급은 회원 인증 페이지를 참고하세요.

ZeroTalk.init({
  pluginKey: "YOUR_PLUGIN_KEY",
  apiBaseUrl: "https://api.talk.zeroworks.ai/api/v1",
  wsUrl: "wss://api.talk.zeroworks.ai/ws/sdk",
  memberId: "user-123",
  memberHash: "HMAC_HASH",
  profile: {
    name: "홍길동",
    email: "hong@example.com",
  },
});

JavaScript API

위젯 초기화 후 인스턴스 핸들로 위젯을 제어합니다.

HTML / Vanilla
React

전역 ZeroTalk.getInstance() 로 초기화된 위젯 핸들을 얻은 뒤 메서드를 호출합니다.

const widget = ZeroTalk.getInstance();
widget?.open();
widget?.close();
widget?.toggle();

// 런처 / 인사 말풍선 숨김은 init 옵션을 변경하거나 위젯을 destroy → init 으로
// 다시 띄워서 적용합니다.
ZeroTalk.destroy();
ZeroTalk.init({
  pluginKey: "YOUR_PLUGIN_KEY",
  apiBaseUrl: "https://api.talk.zeroworks.ai/api/v1",
  wsUrl: "wss://api.talk.zeroworks.ai/ws/sdk",
  hideLauncher: true,
  hideGreeting: true,
});

useZeroTalk() 훅은 보다 풍부한 제어 API를 제공합니다.

import { useZeroTalk } from "@zerotalk/react-sdk";

function ChatButton() {
  const {
    open,
    close,
    toggle,
    showLauncher,
    hideLauncher,
    showGreeting,
    hideGreeting,
    isReady,
    connectionStatus,
  } = useZeroTalk();

  return (
    <button onClick={toggle} disabled={!isReady}>
      채팅
    </button>
  );
}

옵션​

테두리 설정​

사용자 정보 연동​

JavaScript API​

옵션

테두리 설정

사용자 정보 연동

JavaScript API