설치

ZeroTalk 채팅 위젯은 한 줄의 스크립트로 어떤 웹사이트에든 추가됩니다. 설치를 마치면 우측 하단에 채팅 버블이 나타나며, 방문자는 즉시 상담을 시작할 수 있습니다.

사전 준비

대시보드 → 채팅 설정 → 연동 / 개발 → 연동 설정 → 웹사이트 카드 로 들어간 뒤, 화면 아래쪽 Plugin Key 관리 → + 키 생성 에서 Plugin Key (pk_live_...) 를 발급받습니다.

키를 만들거나 고칠 때 허용 도메인을 지정하면 그 도메인에서만 키가 동작합니다. example.com 처럼 호스트명만 입력하며, 스킴(https://)·경로·포트는 넣을 수 없습니다.

• *.example.com 은 example.com 과 모든 하위 도메인(shop.example.com, m.shop.example.com 등)을 허용합니다.
• example.com 과 www.example.com 은 같은 도메인으로 취급합니다.
• 비워 두면 도메인 제한이 없습니다. 도메인을 지정했다면 Origin·Referer 헤더가 없는 요청은 거절됩니다.
• 최대 100개까지 등록할 수 있습니다.

키 값 전체가 보이는 건 생성 직후 한 번뿐입니다

키를 만들면 Plugin Key 와 Secret Key 전체 값이 한 번 표시되고, 창을 닫으면 목록에는 pk_live_****1a2b 처럼 뒤 네 자리만 남습니다. 재발급 기능은 없으므로 그 자리에서 복사해 두세요. 잃어버렸다면 그 키를 폐기하고 새로 만들어야 합니다.

Plugin Key vs Secret Key

Plugin Key 는 클라이언트(HTML)에 노출되어도 안전한 공개 식별자입니다.

회원 인증을 추가하려면 같은 화면에서 발급되는 Secret Key 를 자사 백엔드에 별도로 보관하세요 — 자세한 내용은 회원 인증 페이지를 참고합니다.

설치

사이트 환경에 맞는 탭의 코드를 넣습니다. HTML 탭의 코드는 </body> 바로 위에 추가하고, 다른 탭은 그 탭의 설명을 따릅니다.

HTML

index.html

<script src="https://cdn.talk.zeroworks.ai/latest/chat-widget.iife.js"></script>
<script>
  ZeroTalk.init({
    pluginKey: "YOUR_PLUGIN_KEY",
    apiBaseUrl: "https://api.talk.zeroworks.ai/api/v1",
    wsUrl: "wss://api.talk.zeroworks.ai/ws/sdk",
  });
</script>

Pure JS (async)

위젯 스크립트를 비동기로 로드하면서 페이지 렌더링을 막지 않습니다. </body> 바로 위, 또는 <head> 어디에든 한 블록을 넣을 수 있습니다.

index.html

<script>
  (function () {
    var w = window;
    if (w.ZeroTalk) return w.console.error("ZeroTalk loaded twice");
    var z = function () {
      z.q.push(typeof arguments[0] === "string" ? arguments : ["init", arguments]);
    };
    z.q = [];
    ["init", "identify", "logout", "destroy"].forEach(function (m) {
      z[m] = function () { z.q.push([m, arguments]); };
    });
    w.ZeroTalk = z;
    var s = document.createElement("script");
    s.async = true;
    s.src = "https://cdn.talk.zeroworks.ai/latest/chat-widget.iife.js";
    document.head.appendChild(s);
  })();
  ZeroTalk.init({
    pluginKey: "YOUR_PLUGIN_KEY",
    apiBaseUrl: "https://api.talk.zeroworks.ai/api/v1",
    wsUrl: "wss://api.talk.zeroworks.ai/ws/sdk",
  });
</script>

번들이 로드되기 전에 호출한 ZeroTalk.init() · identify() · logout() · destroy() 는 큐에 쌓였다가, 스크립트가 준비되면 순서대로 실행됩니다.

React

React SDK 는 npm 공개 출시 준비 중입니다

@zerotalk/react-sdk 패키지는 아직 npm 레지스트리에 공개 배포되지 않았습니다. 그 전까지는 아래 HTML / Pure JS 탭의 IIFE 스크립트를 React 앱의 index.html (또는 Next.js app/layout.tsx) 에 그대로 넣어 사용할 수 있습니다. 공개 시점이 정해지면 본 가이드를 갱신합니다.

공개 출시 후에는 다음과 같이 사용합니다.

npm install @zerotalk/react-sdk

App.tsx

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

export default function App() {
  return (
    <>
      {/* 다른 컴포넌트들 */}
      <ZeroTalk
        pluginKey="YOUR_PLUGIN_KEY"
        apiBaseUrl="https://api.talk.zeroworks.ai/api/v1"
        wsUrl="wss://api.talk.zeroworks.ai/ws/sdk"
      />
    </>
  );
}

Next.js (App Router)

React SDK 는 npm 공개 출시 준비 중입니다

공개 배포 전입니다. Next.js 에서도 우선 IIFE 스크립트를 app/layout.tsx 의 <head> 또는 next/script 컴포넌트로 로드하는 방식을 권장합니다.

공개 출시 후에는 다음과 같이 사용합니다.

npm install @zerotalk/react-sdk

app/layout.tsx

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

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>
        {children}
        <ZeroTalk
          pluginKey={process.env.NEXT_PUBLIC_ZEROTALK_PLUGIN_KEY!}
          apiBaseUrl="https://api.talk.zeroworks.ai/api/v1"
          wsUrl="wss://api.talk.zeroworks.ai/ws/sdk"
        />
      </body>
    </html>
  );
}

YOUR_PLUGIN_KEY 를 발급받은 키로 교체합니다.

apiBaseUrl 과 wsUrl 은 반드시 넣으세요

두 옵션의 기본값은 절대 주소가 아니라 상대경로(/api/v1, /ws/sdk)입니다. 생략하면 위젯이 제로톡 서버가 아니라 자사 도메인으로 요청하게 됩니다.

• apiBaseUrl 을 빠뜨리면 부팅 요청이 자사 도메인의 /api/v1/sdk/boot 로 가서 404 또는 501 에러로 위젯이 뜨지 않습니다.
• wsUrl 을 빠뜨리면 실시간 연결이 자사 도메인의 /ws/sdk 로 붙으려다 실패하고, 몇 번 재시도한 뒤 롱 폴링으로 전환됩니다. 대화는 되지만 메시지 반영이 느려집니다.

설치 확인

브라우저에서 페이지를 새로고침하고 다음을 확인합니다.

확인 항목	정상 동작
우측 하단	채팅 버블 버튼이 표시됨
버튼 클릭	채팅창이 열리며 워크스페이스 정보 표시
DevTools → Network → sdk/boot/config (또는 sdk/boot)	200 OK
첫 메시지를 보낸 뒤 DevTools → Network → wss://...	101 Switching Protocols
DevTools → Console	에러 없음

WebSocket 은 첫 메시지 이후에 붙습니다

위젯은 방문자가 실제로 대화를 시작하기 전까지 세션을 만들지 않습니다. 그래서 페이지를 열거나 채팅창을 열기만 해서는 wss:// 연결이 잡히지 않습니다 — 설치가 잘못된 것이 아닙니다. 메시지를 한 번 보낸 뒤에 확인하세요.

위젯이 뜨지 않을 때

증상	원인과 해결
콘솔에 ZeroTalk: pluginKey or loungeSlug is required	init() 에 pluginKey 가 없습니다. 발급받은 Plugin Key 를 넣으세요
sdk/boot 응답에 INVALID_KEY_FORMAT	pluginKey 가 Plugin Key 형식이 아닙니다. 가려진 값(pk_live_****1a2b)이나 YOUR_PLUGIN_KEY 를 그대로 쓰지 않았는지 확인하세요
sdk/boot 응답에 DOMAIN_NOT_ALLOWED	페이지의 도메인이 그 키의 허용 도메인에 없습니다. 대시보드 Plugin Key 관리에서 도메인을 추가하세요
sdk/boot 요청이 자사 도메인으로 감	apiBaseUrl 을 넣지 않았습니다. 위 경고를 참고하세요
아무 에러 없이 위젯이 없음	검색 엔진 크롤러 같은 봇으로 판정되면 위젯을 띄우지 않고, 콘솔에 bot environment detected; widget disabled 만 남깁니다(debug 레벨이라 콘솔의 Verbose 표시를 켜야 보입니다)

다음 단계

• 위젯 커스터마이징 — 색상, 위치, 인사 메시지, 런처 아이콘 설정
• 회원 인증 — 로그인 사용자 식별과 HMAC 서명
• 위젯 커스터마이징(대시보드) — 코드 없이 대시보드에서 바꾸는 설정