설치
ZeroTalk 채팅 위젯은 한 줄의 스크립트로 어떤 웹사이트에든 추가됩니다. 설치를 마치면 우측 하단에 채팅 버블이 나타나며, 방문자는 즉시 상담을 시작할 수 있습니다.
사전 준비
대시보드 → 채팅 설정 → 연동 / 개발 → 연동 설정 → 웹사이트 카드 로 들어간 뒤, 화면 아래쪽 Plugin Key 관리 → + 키 생성 에서 Plugin Key (pk_live_...) 를 발급받습니다.
키를 만들면 Plugin Key 와 Secret Key 전체 값이 한 번 표시되고, 창을 닫으면 목록에는 pk_live_****1a2b 처럼 뒤 네 자리만 남습니다. 재발급 기능은 없으므로 그 자리에서 복사해 두세요. 잃어버렸다면 그 키를 폐기하고 새로 만들어야 합니다.
Plugin Key 는 클라이언트(HTML)에 노출되어도 안전한 공개 식별자입니다.
회원 인증을 추가하려면 같은 화면에서 발급되는 Secret Key 를 자사 백엔드에 별도로 보관하세요 — 자세한 내용은 회원 인증 페이지를 참고합니다.
설치
</body> 바로 위에 다음 코드를 추가합니다.
- HTML
- Pure JS (async)
- React
- Next.js (App Router)
<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>
위젯 스크립트를 비동기로 로드하면서 페이지 렌더링을 막지 않습니다. </body> 바로 위, 또는 <head> 어디에든 한 블록을 넣을 수 있습니다. 대시보드의 설치 코드 카드가 주는 것과 같은 형태입니다.
<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() 는 큐에 쌓였다가, 스크립트가 준비되면 순서대로 실행됩니다.
@zerotalk/react-sdk 패키지는 아직 npm 레지스트리에 공개 배포되지 않았습니다. 그 전까지는 아래 HTML / Pure JS 탭의 IIFE 스크립트를 React 앱의 index.html (또는 Next.js app/layout.tsx) 에 그대로 넣어 사용할 수 있습니다. 공개 시점이 정해지면 본 가이드를 갱신합니다.
공개 출시 후에는 다음과 같이 사용합니다.
npm install @zerotalk/react-sdk
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 에서도 우선 IIFE 스크립트를 app/layout.tsx 의 <head> 또는 next/script 컴포넌트로 로드하는 방식을 권장합니다.
공개 출시 후에는 다음과 같이 사용합니다.
npm install @zerotalk/react-sdk
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로 붙으려다 실패하고, 몇 번 재시도한 뒤 롱 폴링으로 전환됩니다. 대화는 되지만 메시지 반영이 느려집니다.
Plugin Key 관리 위에 있는 설치 코드 카드는 CDN 주소와 apiBaseUrl 이 채워진 스니펫을 바로 복사해 줍니다. 다만 두 가지를 직접 손봐야 합니다.
pluginKey를 전체 키로 교체 — 카드가 채워 주지 않는 유일한 값입니다. 그 자리에{PLUGIN_KEY}가 있든pk_live_****1a2b같은 가려진 값이 있든, 키를 만들 때 복사해 둔 전체 키로 바꿔야 위젯이 뜹니다.wsUrl추가 — 대시보드 스니펫에는wsUrl이 들어 있지 않습니다. 위 경고대로 직접 넣어야 실시간 연결이 붙습니다.
설치 확인
브라우저에서 페이지를 새로고침하고 다음을 확인합니다.
| 확인 항목 | 정상 동작 |
|---|---|
| 우측 하단 | 채팅 버블 버튼이 표시됨 |
| 버튼 클릭 | 채팅창이 열리며 워크스페이스 정보 표시 |
DevTools → Network → sdk/boot/config (또는 sdk/boot) | 200 OK |
첫 메시지를 보낸 뒤 DevTools → Network → wss://... | 101 Switching Protocols |
| DevTools → Console | 에러 없음 |
위젯은 방문자가 실제로 대화를 시작하기 전까지 세션을 만들지 않습니다. 그래서 페이지를 열거나 채팅창을 열기만 해서는 wss:// 연결이 잡히지 않습니다 — 설치가 잘못된 것이 아닙니다. 메시지를 한 번 보낸 뒤에 확인하세요.
다음 단계
- 위젯 커스터마이징 — 색상, 위치, 인사 메시지, 런처 아이콘 설정
- 회원 인증 — 로그인 사용자 식별과 HMAC 서명
- 위젯 커스터마이징(대시보드) — 코드 없이 대시보드에서 바꾸는 설정