> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt > Use this file to discover all available pages before exploring further. # 위젯 개요 > 웹사이트 방문자가 페이지를 떠나지 않고 에이전트와 채팅하거나 통화하고, 전화를 요청하게 하세요. 위젯은 웹사이트에 붙이는 상담 창입니다. 방문자는 페이지를 떠나지 않고 에이전트와 채팅하거나 통화하거나 전화를 요청하고 그 내용은 [고객](/docs/operate/monitor/customers)에 방문자별로 쌓입니다.

## 위젯으로 할 수 있는 일 위젯 하나에 유형 하나를 정합니다. 방문자가 무엇을 하러 오는지에 맞추세요. 영업시간 밖에도 질문에 답하고 문의를 접수합니다. 문의가 많고 글로 충분할 때 고릅니다. 번호를 찾아 걸 필요 없이 브라우저에서 바로 통화하고 통화 중에는 텍스트도 보낼 수 있습니다. 말로 설명해야 빠른 문의에 맞습니다. 방문자가 번호를 남기면 에이전트가 전화를 겁니다. 지금 통화하기 어려운 방문자도 놓치지 않습니다. 어느 유형이든 설치 코드로 방문자 ID와 페이지 값을 넘길 수 있습니다. 재방문 고객을 알아보거나 상품 정보를 프롬프트에 넣은 채로 상담을 시작하세요. ## 설치하고 게시하기 **배포 > 위젯**에서 **새 위젯**을 누르고 **위젯 제목**, **위젯 유형**, **에이전트**를 고른 뒤 **만들기**를 누릅니다. 제목은 위젯 창 상단에 표시됩니다. 전화 콜백은 발신에 쓸 전화번호가 있어야 하므로 [위젯 유형](/docs/operate/deploy/widget/modes)의 준비할 것을 먼저 확인하세요. 색, 위치, 인사 메시지, 자동 열기는 [모양과 메시지](/docs/operate/deploy/widget/appearance)에서 바꾸고 화면 하단의 미리보기로 확인합니다.

우측 상단 **임베드 코드**를 눌러 복사하고 웹페이지의 `` 또는 ``에 붙여넣습니다. 아래는 형식 예시이며 `data-widget-id`에는 복사한 코드의 공개 ID가 들어 있습니다. ```html theme={null} ``` API 키나 에이전트 ID는 페이지에 넣지 않습니다. **설치 도메인**은 위젯이 동작할 사이트입니다. 대시보드에서 만든 위젯은 기본값 `*`로 모든 도메인에서 동작하므로 처음에는 그대로 두어도 됩니다. `example.com`처럼 특정 도메인만 등록하면 그 사이트와 하위 도메인에서만 동작하므로 개발 중에는 `localhost`와 `127.0.0.1`을 함께 넣어야 로컬에서 확인됩니다. 목록을 비우면 게시해도 어떤 사이트에서도 표시되지 않습니다. **사이트에 게시**를 켜면 설치된 웹사이트에 위젯이 나타납니다. 게시 전에는 스크립트를 설치해도 표시되지 않고 이미 열어 둔 페이지는 다시 열어야 보입니다. ## 게시본 바꾸기 게시 중인 위젯을 수정하고 **저장**하면 **게시 검토**가 열려 현재 게시본과 새 버전의 차이를 보여 줍니다. **저장하고 게시**를 누르면 설치된 모든 사이트에 적용되고 방문자에게는 페이지를 다시 열 때부터 반영됩니다.

**사이트에 게시**를 끄면 새로 페이지를 여는 방문자부터 위젯이 보이지 않습니다. 설정은 남아 있으므로 다시 켜면 새 버전으로 게시됩니다. 목록의 **삭제**는 되돌릴 수 없고 설치된 사이트에서 즉시 동작을 멈춥니다. ## 방문자와 페이지 정보 넘기기 * **재방문 고객을 알아볼 때** — 서비스가 관리하는 사용자 키를 `data-visitor-id`로 넘깁니다. 채팅과 브라우저 통화가 같은 고객으로 이어집니다. 규칙은 [방문자 식별](/docs/operate/deploy/widget/visitors)을 참고하세요. * **상품이나 주문 정보를 프롬프트에 넘길 때** — 에이전트 프롬프트의 `{{변수}}`에 들어갈 값을 `data-dynamic`으로 페이지마다 넘깁니다. 위젯의 **동적 변수**에 등록한 키만 반영되고 값은 문자열만 씁니다. 전화 콜백 폼에 방문자가 입력한 값이 있으면 그 값이 우선합니다. 변수 정의는 [동적 변수](/docs/build/variables/dynamic-variables)를 참고하세요. ```html theme={null} ``` ## 설치 페이지와 연동하기 게시된 위젯이면 별도 설정 없이 페이지 스크립트에서 바로 제어할 수 있습니다. * **페이지 버튼으로 위젯을 열 때** — `window.VoxWidget.open()`을 호출합니다. 이미 열린 상태면 아무 일도 하지 않습니다. 닫을 때는 `window.VoxWidget.close()`를 씁니다. * **위젯 상태에 따라 페이지 요소를 바꿀 때** — `vox:widget` 이벤트를 받습니다. 열리거나 닫힐 때마다 한 번 발생합니다. ```html theme={null} ``` `detail.type`은 `open` 또는 `close`이고, `detail.widget_id`는 설치 코드의 공개 ID입니다. ## 설치 속성 | 속성 | 필수 | 설명 | | ----------------- | --- | ------------------------------------------ | | `data-widget-id` | 예 | 위젯마다 발급되는 공개 ID입니다. `wgt_`로 시작합니다. | | `data-visitor-id` | 아니요 | 서비스가 관리하는 방문자 ID입니다. 생략하면 브라우저별로 자동 생성됩니다. | | `data-dynamic` | 아니요 | 페이지에서 덮어쓸 동적 변수입니다. JSON 객체이고 값은 문자열만 씁니다. | ## 문제가 생겼을 때 **사이트에 게시**가 켜져 있는지, **설치 도메인**에 그 사이트가 들어 있는지 확인하세요. 방문자에게는 페이지를 다시 열 때부터 반영되므로 게시 직후라면 페이지를 새로 여세요. 한 방문자가 1분 동안 시작할 수 있는 대화와 통화 수를 넘긴 것입니다. **남용 방지 > 시작 한도**의 **표준**은 분당 5회, **엄격**은 분당 2회이고 **직접 설정**은 1회부터 30회까지 정합니다. 정상 사용에서도 걸리면 **직접 설정**으로 한도를 올리세요. 반대로 한 방문자가 너무 자주 시작하면 **엄격**으로 낮춥니다. **동적 변수**에 등록하지 않은 키와 잘못된 JSON은 무시하고 게시된 기본값을 씁니다. 키 이름이 등록한 변수와 같은지, 값이 문자열인지 확인하세요. ## 관련 문서 * [위젯 유형](/docs/operate/deploy/widget/modes) — 채팅, 음성, 전화 콜백의 방문자 경험과 전용 항목 * [모양과 메시지](/docs/operate/deploy/widget/appearance) — 색상, 위치, 인사 메시지와 미리보기 * [방문자 식별](/docs/operate/deploy/widget/visitors) — 방문자 ID와 고객 연결 규칙, 메모리 이어 가기 * [API와 CLI](/docs/operate/deploy/widget/api) — 코드와 명령어로 위젯 관리 * [고객](/docs/operate/monitor/customers) — 연결된 방문자의 상담 이력 *** 위젯, Widget, 웹 위젯, 채팅 위젯, 음성 위젯, 전화 콜백, data-widget-id, data-visitor-id, data-dynamic, VoxWidget, vox:widget, 설치 코드, 임베드 코드, 게시