위젯 설치(웹 사이트 연동)

웹사이트에 제로톡 채팅창을 설치하면 방문자의 문의를 대시보드에서 받을 수 있어요. 연동 설정 열기, 웹사이트 연동 추가, Plugin Key 생성, 설치 코드 붙여넣기 순서로 설치해요.

시작하기 전에

소유자·관리자 권한으로 연동 설정을 열어요.
웹사이트 코드를 수정할 담당자를 준비해요.
설치할 웹사이트 주소를 확인해요. 허용 도메인을 지정한다면 실제 접속 도메인과 일치해야 해요.
카페24 쇼핑몰은 카페24 연동 가이드의 설치·위젯 관리 방법도 확인하세요.

설치 순서

연동 설정 페이지 들어가기

워크스페이스 좌측 상단 설정 아이콘 > 채팅 설정 > 연동 / 개발 > 연동 설정

워크스페이스 좌측 상단의 설정(톱니바퀴) 아이콘을 클릭해 채팅 설정으로 이동해요.

이어서 채팅 설정 사이드바에서 연동 / 개발 > 연동 설정 항목을 클릭해 연동 설정 페이지로 이동해요.

연동 설정 화면에서 사이드바의 연동 설정 메뉴가 선택되어 있고 등록된 연동 목록과 연동 추가 버튼이 표시돼요

웹사이트 연동 추가하기

우측 상단 + 연동 추가 버튼을 누르면 서비스 연동 모달이 열려요. 모달에서 웹사이트 항목의 연동하기 버튼을 눌러요.

서비스 연동 창 — 웹사이트·카카오톡·네이버 톡톡·라인·이메일·게시판 문의별로 연동 상태와 연동하기 버튼이 보여요

이미 등록된 웹사이트가 있어도 추가연동 버튼을 눌러 또 하나의 웹사이트 연동을 등록할 수 있어요(예: 프로덕션·스테이징용 위젯을 분리해 운영).

웹사이트 외에 다른 채널도 같은 방식으로 추가해, 모든 문의를 한곳에서 함께 응대할 수 있어요.

Plugin Key 생성하기

추가된 웹사이트 카드를 클릭하면 상세 화면으로 이동해요. 상세 화면은 위쪽이 위젯 설정 카드와 미리보기이고, 그 아래에 설치 방법 과 Plugin Key 관리 카드가 차례로 놓여 있어요. 아래로 스크롤해 Plugin Key 관리 카드의 + 키 생성 버튼을 눌러 위젯에 사용할 Plugin Key를 발급해요.

+ 키 생성 버튼을 누르면 다음 두 가지 항목을 입력하는 모달이 열려요. 둘 다 선택 사항이며, 비워두고 바로 생성 을 눌러도 돼요.

이름 (선택) — 키를 구분할 라벨 (최대 20자, 예: 프로덕션 웹사이트)
허용 도메인 (선택) — 이 키로 위젯을 띄울 수 있는 도메인. Enter 또는 , 로 하나씩 추가하며, 비워두면 모든 도메인에서 사용할 수 있어요

키 생성 모달 — 이름(선택) 입력란과 0/20 글자수, 허용 도메인(선택) 입력란과 추가 버튼, 아래에 취소·생성 버튼이 있다

생성된 키는 Plugin Key 관리 표에 pk_live_****1a2b 처럼 가려진 형태로 나타나요. 한 웹사이트 연동에 키를 여러 개 만들어 환경(개발/스테이징/프로덕션)별로 나눠 쓸 수 있어요. 표에서 이름·키·도메인·상태·생성일을 확인하고, 행 오른쪽 ⋮ 메뉴로 키를 수정하거나 폐기해요.

Plugin Key 관리 카드 — 우측 상단 + 키 생성 버튼, 그 아래 이름·키·도메인·상태·생성일 열을 가진 표. 키는 pk_live_****0f07 처럼 뒤 네 자리만 보이고 상태는 활성 또는 폐기됨으로 표시되며 행 오른쪽에 ⋮ 메뉴가 있다 — 폐기한 키는 회색으로 바뀌고 상태가 폐기됨으로 표시돼요.

키를 만든 직후 화면에서 Plugin Key 와 Secret Key 를 복사해 두세요

키 값 전체가 보이는 화면은 생성 직후 한 번뿐이에요. 이 창을 닫으면 Plugin Key 는 표에서 pk_live_****1a2b 처럼 뒤 네 자리만 남고, Secret Key 는 다시 볼 수 없어요.

Plugin Key — 아래 4단계의 설치 코드에 넣을 값이에요. 반드시 여기서 복사해 두세요.
Secret Key — 로그인 사용자를 식별하는 회원 인증 에 쓰여요. 자사 백엔드의 환경 변수에 안전하게 보관하세요. 회원 인증을 쓰지 않는다면 무시해도 돼요.

다시 발급하는 기능은 없어요. 값을 잃어버렸다면 새 키를 생성하고 설치 코드와 회원 인증에 사용하는 설정을 함께 교체하세요. 새 Secret Key를 사용하는 인증에서는 회원 인증값도 새로 계산해야 해요. 이전 키를 폐기하면 그 키를 사용하는 웹사이트에 영향이 있으므로 교체 적용을 먼저 확인하세요.

설치 코드 사이트에 붙여넣기

대시보드는 설치 코드를 직접 보여 주지 않아요. 설치 방법 카드의 ZeroTalk Docs 설치 가이드 열기 링크를 누르면 위젯 설치 가이드 가 열려요. 그 문서에서 사이트 환경에 맞는 탭을 고르세요 — HTML·Pure JS (async)·React·Next.js (App Router) 가 있어요. HTML 탭의 코드는 위젯을 띄울 웹사이트의 </body> 태그 바로 위에 붙여넣어요. 다른 탭은 그 탭의 설명대로 넣어요. 코드에는 ZeroTalk 의 CDN 주소와 API 주소가 이미 채워져 있어요.

붙여넣기 전에 pluginKey 를 실제 키 값으로 바꾸세요

설치 코드의 pluginKey 자리는 직접 채워야 해요. 3단계에서 키를 만들 때 복사해 둔 전체 Plugin Key 로 바꿔주세요.

설치 가이드의 코드에는 그 자리에 YOUR_PLUGIN_KEY 가 들어 있어요. 표에 보이는 pk_live_****1a2b 는 뒤 네 자리만 남긴 가려진 값이라, 그 값을 넣어도 위젯이 뜨지 않아요.

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>

위 코드의 CDN·API 주소는 ZeroTalk 운영 환경의 주소예요. pluginKey 만 내 키로 바꾸면 그대로 쓸 수 있어요.

페이지가 뜨는 것을 막지 않도록 스크립트를 비동기로 불러오려면 Pure JS (async) 탭을, React·Next.js 를 쓰면 그 탭을 고르세요. 환경별 설명은 위젯 설치 가이드 에 있어요.

도움말

스크립트를 붙여넣고 사이트를 새로고침했을 때 설정한 위치에 채팅 버튼이 나타나면 연동이 완료된 거예요. 표시되지 않는다면 위젯 설치 가이드의 설치 확인 표로 점검해보세요.

설치 확인하기

실제 고객이 방문할 웹사이트를 새 창에서 열어요.
채팅 버튼을 열고 테스트 문의를 보내요.
제로톡 대화에서 문의를 확인하고 답장해요.
웹사이트 채팅창에서 답장을 확인해요.

문의 확인하고 답장하기에서 자세한 응대 순서를 확인하세요.

문제 해결

상황	확인할 것
채팅 버튼이 보이지 않아요	전체 Plugin Key 입력 여부, 키의 활성 상태, 허용 도메인, 위젯 노출 설정을 확인해요.
PC에서는 보이는데 모바일에서는 안 보여요	모바일 웹의 버튼 숨기기와 설치 코드가 모바일 페이지에도 적용됐는지 확인해요.
문의를 보냈는데 찾을 수 없어요	설치 키를 발급한 워크스페이스인지, 대화 목록의 서비스·상담원 필터가 걸려 있는지 확인해요.
회원 인증을 켠 뒤 문의를 시작할 수 없어요	웹사이트 담당자와 회원 인증 설정을 확인해요. Secret Key를 고객 화면의 설치 코드에 넣지 않아요.

시작하기 전에​

설치 순서​

설치 확인하기​

문제 해결​

시작하기 전에

설치 순서

설치 확인하기

문제 해결