> ## 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.
# API와 CLI
> v3 위젯 API와 vox CLI로 위젯 설정과 게시 상태를 관리하세요.
대시보드의 **배포 > 위젯**에서 다루는 위젯을 v3 API와 vox CLI로도 만들고, 수정하고, 게시할 수 있습니다. 이 페이지는 식별자, 상태, 설정 필드, 오류를 정리합니다.
## 엔드포인트
모든 관리 작업은 `/v3/widgets` 아래의 7개 엔드포인트를 사용합니다.
| 메서드 | 경로 | 하는 일 |
| -------- | ----------------------------------- | -------------------- |
| `GET` | `/v3/widgets` | 위젯 목록을 조회합니다. |
| `POST` | `/v3/widgets` | 위젯을 생성합니다. |
| `GET` | `/v3/widgets/{widget_id}` | 위젯 한 개를 조회합니다. |
| `PATCH` | `/v3/widgets/{widget_id}` | 위젯 설정을 수정합니다. |
| `DELETE` | `/v3/widgets/{widget_id}` | 위젯을 보관 상태로 바꿉니다. |
| `POST` | `/v3/widgets/{widget_id}/publish` | 현재 설정을 새 버전으로 게시합니다. |
| `POST` | `/v3/widgets/{widget_id}/unpublish` | 게시를 해제합니다. |
전체 파라미터는 [API 레퍼런스 소개](/api-reference/v3/introduction)의 **위젯** 그룹에서 확인하세요.
### 요청과 응답 규격
| 구분 | 계약 |
| -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 생성 | `agent.agent_id`는 필수입니다. `agent.agent_version`을 생략하면 `current`입니다. `mode`의 기본값은 `chat`입니다. `allowed_domains`의 기본값은 `[]`입니다. `callback_from_number`, `callback_presentation_number`, `rate_limit`의 기본값은 `null`입니다. `branding`을 생략하면 모든 항목이 `null`인 객체로 돌아옵니다. |
| 수정 | 생성 필드를 모두 선택적으로 받습니다. `null`을 보내 콜백 번호와 `rate_limit`을 지울 수 있습니다. `branding`을 보내면 기존 `branding` 전체를 교체합니다. |
| 응답 | `id`는 UUID이고 `public_id`는 문자열입니다. `organization_id`는 UUID이고 `agent`는 객체입니다. `status`는 `draft`, `published`, `archived` 중 하나입니다. `mode`는 `chat`, `voice`, `callback` 중 하나입니다. 두 콜백 번호는 문자열 또는 `null`입니다. `allowed_domains`는 문자열 배열입니다. `rate_limit`은 객체 또는 `null`이고 `branding`은 객체입니다. `published_at`은 밀리초 단위 정수 또는 `null`입니다. `published_version_id`는 UUID 또는 `null`입니다. `created_at`과 `updated_at`은 밀리초 단위 정수입니다. |
API로 위젯을 만들 때는 `allowed_domains`를 명시하세요. 생략하면 빈 목록이 됩니다. 게시해도 어떤 사이트에서도 위젯이 나타나지 않습니다.
`status`와 `public_id`는 생성 또는 수정 요청으로 바꿀 수 없습니다.
## 생성, 게시, 조회
생성, 게시, 조회 순서로 호출하세요.
`POST /v3/widgets`로 초안을 만듭니다. `agent.agent_id`와 `allowed_domains`를 넣으세요.
```bash theme={null}
curl https://client-api.tryvox.co/v3/widgets \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"agent": {
"agent_id": "",
"agent_version": "current"
},
"allowed_domains": ["example.com"]
}'
```
응답의 `status`는 `draft`입니다. `public_id`는 `wgt_`로 시작합니다. `published_version_id`는 `null`입니다.
```json theme={null}
{
"id": "11111111-1111-4111-8111-111111111111",
"public_id": "wgt_4aab36e2c2d74e9e829e26eb7f5777d1",
"status": "draft",
"allowed_domains": ["example.com"],
"published_at": null,
"published_version_id": null
}
```
현재 설정을 새 버전으로 게시합니다. 경로 파라미터 `widget_id`에는 생성 응답의 `id`를 넣습니다.
```bash theme={null}
curl -X POST https://client-api.tryvox.co/v3/widgets//publish \
-H "Authorization: Bearer "
```
응답의 `status`는 `published`입니다. `published_version_id`에 UUID가 들어갑니다.
```json theme={null}
{
"id": "11111111-1111-4111-8111-111111111111",
"public_id": "wgt_4aab36e2c2d74e9e829e26eb7f5777d1",
"status": "published",
"allowed_domains": ["example.com"],
"published_at": 1710000000000,
"published_version_id": "22222222-2222-4222-8222-222222222222"
}
```
게시한 위젯을 확인합니다.
```bash theme={null}
curl https://client-api.tryvox.co/v3/widgets/ \
-H "Authorization: Bearer "
```
응답의 `status`, `public_id`, `published_version_id`는 게시 결과와 같습니다.
```json theme={null}
{
"id": "11111111-1111-4111-8111-111111111111",
"public_id": "wgt_4aab36e2c2d74e9e829e26eb7f5777d1",
"status": "published",
"allowed_domains": ["example.com"],
"published_at": 1710000000000,
"published_version_id": "22222222-2222-4222-8222-222222222222"
}
```
## id와 public\_id
경로 파라미터 `widget_id`에는 응답의 `id`를 넣습니다. `id`는 UUID입니다. API와 CLI는 이 값으로 위젯을 가리킵니다.
설치 코드의 `data-widget-id`에는 `public_id`를 넣습니다. `public_id`는 서버가 발급하는 읽기 전용 문자열이며 `wgt_`로 시작합니다.
```html theme={null}
```
## 상태 수명주기
| 현재 상태 | 작업 | 다음 상태 | 보존되는 정보 |
| ----------- | ----- | ----------- | -------------------------- |
| 새 위젯 | 생성 | `draft` | 현재 설정 |
| `draft` | 게시 | `published` | 현재 설정을 담은 새 버전 |
| `published` | 다시 게시 | `published` | 기존 버전과 새 버전 |
| `published` | 게시 해제 | `draft` | 마지막 게시 스냅샷과 `published_at` |
| 모든 상태 | 삭제 | `archived` | 위젯 레코드 |
게시할 때마다 현재 초안을 새 버전으로 추가합니다. `unpublish`는 마지막 게시 스냅샷과 `published_at`을 유지합니다. `delete`는 위젯을 완전히 삭제하지 않고 `archived` 상태로 남깁니다. 복구 엔드포인트는 제공하지 않습니다.
게시 중인 위젯을 `PATCH`하면 설치된 위젯에 바로 반영되지 않습니다. 변경 사항을 적용하려면 `publish`를 다시 호출하세요.
## 설정 필드와 대시보드 항목
대시보드 라벨에 해당하는 API 필드는 다음과 같습니다.
| 대시보드 라벨 | API 필드 또는 작업 |
| ------------------------------- | ------------------------------------------------------------------------------------------------ |
| **사이트에 게시** | `publish`, `unpublish`, 응답 `status` |
| **위젯 제목** | `branding.title` |
| **위젯 유형** | `mode` |
| **에이전트** | `agent.agent_id`, `agent.agent_version` |
| **설치 도메인** | `allowed_domains` |
| **발신번호** | `callback_from_number` |
| **표시번호** | `callback_presentation_number` |
| **콜백 폼 입력 항목** | `branding.callback_fields` |
| **약관 URL** | `branding.terms_url` |
| **강조 색상** | `branding.accent_color` |
| **아바타 색상 직접 지정**, **아바타 색상** | `branding.orb_colors.primary`, `branding.orb_colors.secondary` |
| **모서리** | `branding.styles.button_radius`, `branding.styles.input_radius`, `branding.styles.bubble_radius` |
| **다크 모드** | `branding.theme` |
| **로고 이미지 URL** | `branding.logo_url` |
| **인사 메시지** | `branding.popup_message` |
| **인사 메시지 지연** | `branding.popup_delay_seconds` |
| **페이지 로드 시 자동 열기** | `branding.auto_open` |
| **추천 답변** | `branding.suggested_replies` |
| **면책 문구** | `branding.disclaimer_text` |
| **마크다운 형식** | `branding.markdown` |
| **모든 도메인 링크 허용**, **링크 허용 도메인** | `branding.link_allowed_hosts` |
| **통화 내용 텍스트 표시** | `branding.transcript` |
| **위젯 버튼 텍스트** | `branding.fab_text` |
| **위치** | `branding.placement` |
| **패널 크기** | `branding.panel_size` |
| **Powered by vox.ai 숨기기** | `branding.white_label` |
| **동적 변수** | `branding.dynamic_variables` |
| **시작 한도**, **분당 시작 한도** | `rate_limit.preset`, `rate_limit.per_minute` |
## 오류
| 상태 코드 | 조건 | 처리 방법 |
| ----- | ------------------------------------- | ------------------------- |
| `400` | `PATCH` 본문이 비어 있습니다. | 바꿀 필드를 하나 이상 보내세요. |
| `409` | `archived` 위젯을 수정하려고 합니다. | 다른 위젯을 사용하거나 새로 만드세요. |
| `409` | `published` 상태가 아닌 위젯의 게시를 해제하려고 합니다. | 응답 `status`를 확인한 뒤 호출하세요. |
| `204` | 이미 `archived`인 위젯을 다시 삭제합니다. | 성공으로 처리하세요. |
## CLI로 관리하기
모든 명령은 다음 공통 플래그를 지원합니다.
* `--profile `
* `--org `
* `--json`
| 명령 | 인자와 플래그 | 예시 |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `list` | `--status `는 여러 번 지정할 수 있습니다. `--mode `, `--sort-order `, `--limit `, `--cursor ` | `vox widget list --status published --mode chat --sort-order desc --limit 20` |
| `get` | ``, `--snippet` | `vox widget get --snippet` |
| `create` | 필수 `--agent-id `, `--mode `. 선택 `--agent-version `, `--allowed-domains a.com,b.com`, `--rate-limit `, `--branding `, `--callback-from-number `, `--callback-presentation-number ` | `vox widget create --agent-id --mode chat --allowed-domains example.com` |
| `update` | ``와 생성 명령의 선택 플래그. 최소 한 개가 필요합니다. `--agent-version`은 `--agent-id`와 함께 사용합니다. | `vox widget update --mode voice` |
| `delete` | ``, `--yes` | `vox widget delete --yes` |
| `publish` | `` | `vox widget publish ` |
| `unpublish` | `` | `vox widget unpublish ` |
설치 코드가 필요하면 `get --snippet`을 실행하세요. 출력에는 `public_id`가 들어갑니다.
## 관련 문서
* [위젯 개요](/docs/operate/deploy/widget/overview) — 위젯 만들기, 설치, 게시
* [API 레퍼런스 소개](/api-reference/v3/introduction) — v3 API 인증과 요청 형식
* [CLI](/docs/ai/cli) — vox CLI 설치와 인증
***
위젯 API, /v3/widgets, vox widget, public\_id, widget\_id, publish, unpublish, CLI