설치
ZeroTalk 채팅 위젯은 한 줄의 스크립트로 어떤 웹사이트에든 추가됩니다. 설치를 마치면 우측 하단에 채팅 버블이 나타나며, 방문자는 즉시 상담을 시작할 수 있습니다.
사전 준비
대시보드 → 채팅 설정 → 연동 / 개발 → 연동 설정 → 웹사이트 카드 → Plugin Key 관리 → + 키 생성 에서 Plugin Key (pk_live_...) 를 발급받습니다.
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 q = [];
w.ZeroTalk = {
init: function (o) { q.push(["init", o]); },
destroy: function () { q.push(["destroy"]); },
};
var s = document.createElement("script");
s.async = true;
s.src = "https://cdn.talk.zeroworks.ai/latest/chat-widget.iife.js";
s.onload = function () {
for (var i = 0; i < q.length; i++) {
var fn = w.ZeroTalk[q[i][0]];
if (typeof fn === "function") fn.call(w.ZeroTalk, q[i][1]);
}
};
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(...) 호출은 번들 로드 전에 큐에 적재되었다가, 스크립트가 준비되면 자동으로 실행됩니다.
@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/sdk/boot)로 호출되어 404 또는 501 에러로 로드되지 않습니다.
설치 확인
브라우저에서 페이지를 새로고침하고 다음을 확인합니다.
| 확인 항목 | 정상 동작 |
|---|---|
| 우측 하단 | 채팅 버블 버튼이 표시됨 |
| 버튼 클릭 | 채팅창이 열리며 워크스페이스 정보 표시 |
DevTools → Network → boot | 200 OK |
DevTools → Network → wss://... | 101 Switching Protocols |
| DevTools → Console | 에러 없음 |