> ## 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.

# Widget

> 웹사이트에 채팅과 음성 대화를 추가하고 같은 방문자의 Customer 이력을 이어 가세요.

Widget은 웹사이트 방문자가 vox.ai 에이전트와 채팅하거나 음성으로 대화할 수 있게
합니다. 대시보드에서 Widget을 발행한 뒤 설치 코드를 웹페이지에 추가하세요.

## 설치하기

`data-widget-id`에는 대시보드에서 발행한 Widget ID를 넣습니다.

```html theme={null}
<script
  src="https://app.tryvox.co/widget-v1.js"
  data-widget-id="wgt_example"
  async
></script>
```

`data-widget-id`가 Widget 설정과 연결할 에이전트를 결정합니다. 브라우저에 API
키나 Agent ID를 넣지 않습니다.

## 방문자를 같은 Customer로 연결하기

Widget은 브라우저에 안정적인 방문자 ID를 만들고 다음 방문에도 재사용합니다.
같은 브라우저와 조직에서 시작한 채팅·음성 세션은 같은 Customer에 연결됩니다.

서비스가 방문자 ID를 이미 관리한다면 `data-visitor-id`로 직접 전달하세요.

```html theme={null}
<script
  src="https://app.tryvox.co/widget-v1.js"
  data-widget-id="wgt_example"
  data-visitor-id="visitor_1024"
  async
></script>
```

`data-visitor-id`는 vox.ai 내부 Customer UUID가 아니라 서비스가 관리하는 안정적인
방문자 키입니다. 같은 조직에서 같은 값을 사용하면 다른 Widget 세션도 같은
Customer에 연결됩니다.

<Warning>
  브라우저에 공개되는 `data-visitor-id`는 조작될 수 있습니다.
  로그인 여부나 권한을 판단하는 데 사용하지 마세요.
</Warning>

```mermaid theme={null}
flowchart LR
    A[Widget 실행] --> B{data-visitor-id 있음}
    B -->|있음| C[지정한 방문자 ID 사용]
    B -->|없음| D[브라우저 방문자 ID 생성 또는 재사용]
    C --> E[Customer 조회 또는 생성]
    D --> E
    E --> F[채팅·음성 이력 연결]
```

<Note>
  다른 기기나 시크릿 모드로 접속하거나 브라우저 저장소를 삭제하면 새 익명
  Customer가 생길 수 있습니다. 같은 사람임을 확인한 뒤 Customers API로
  식별자를 추가하거나 중복 Customer를 병합하세요.
</Note>

## Memory 사용하기

에이전트의 Memory가 켜져 있으면 같은 Customer와 에이전트에 저장된 Memory를
첫 응답 전에 자동으로 불러옵니다. Widget에서 Memory를 직접 조회하거나 전달할
필요가 없습니다. 대화가 끝나면 새로 확인한 정보가 기존 추출 파이프라인을 통해
저장됩니다.

자세한 식별 규칙은 [고객](/docs/operate/deploy/customers), 저장과 주입
동작은 [메모리](/docs/build/customer-memory/memory)를 참고하세요.

## 설치 속성

| 속성                | 필수 | 설명                                       |
| ----------------- | -- | ---------------------------------------- |
| `data-widget-id`  | O  | 대시보드에서 발행한 Widget ID                     |
| `data-visitor-id` |    | 서비스가 관리하는 안정적인 방문자 ID. 생략하면 브라우저별로 자동 생성 |

***

<Accordion title="연관 검색어">
  Widget, 웹 위젯, data-widget-id, data-visitor-id, visitor ID, Customer, Memory, 익명 방문자, 채팅 위젯, 음성 위젯
</Accordion>