API와 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 레퍼런스 소개의 위젯 그룹에서 확인하세요.

요청과 응답 규격

구분	계약
생성	`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를 넣으세요.

curl https://client-api.tryvox.co/v3/widgets \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "agent_id": "<agent_id>",
      "agent_version": "current"
    },
    "allowed_domains": ["example.com"]
  }'

응답의 status는 draft입니다. public_id는 wgt_로 시작합니다. published_version_id는 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를 넣습니다.

curl -X POST https://client-api.tryvox.co/v3/widgets/<widget_id>/publish \
  -H "Authorization: Bearer <API_KEY>"

응답의 status는 published입니다. published_version_id에 UUID가 들어갑니다.

{
  "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"
}

조회

게시한 위젯을 확인합니다.

curl https://client-api.tryvox.co/v3/widgets/<widget_id> \
  -H "Authorization: Bearer <API_KEY>"

응답의 status, public_id, published_version_id는 게시 결과와 같습니다.

{
  "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_로 시작합니다.

<script
  src="https://www.tryvox.co/widget-v1.js"
  data-widget-id="wgt_..."
  async
></script>

상태 수명주기

현재 상태	작업	다음 상태	보존되는 정보
새 위젯	생성	`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 <name>
--org <organization-id>
--json

명령	인자와 플래그	예시
`list`	`--status <draft\|published\|archived>`는 여러 번 지정할 수 있습니다. `--mode <chat\|voice\|callback>`, `--sort-order <asc\|desc>`, `--limit <n>`, `--cursor <c>`	`vox widget list --status published --mode chat --sort-order desc --limit 20`
`get`	`<widget-id>`, `--snippet`	`vox widget get <widget-id> --snippet`
`create`	필수 `--agent-id <uuid>`, `--mode <chat\|voice\|callback>`. 선택 `--agent-version <current\|production\|vN>`, `--allowed-domains a.com,b.com`, `--rate-limit <json>`, `--branding <json>`, `--callback-from-number <e164>`, `--callback-presentation-number <e164>`	`vox widget create --agent-id <uuid> --mode chat --allowed-domains example.com`
`update`	`<widget-id>`와 생성 명령의 선택 플래그. 최소 한 개가 필요합니다. `--agent-version`은 `--agent-id`와 함께 사용합니다.	`vox widget update <widget-id> --mode voice`
`delete`	`<widget-id>`, `--yes`	`vox widget delete <widget-id> --yes`
`publish`	`<widget-id>`	`vox widget publish <widget-id>`
`unpublish`	`<widget-id>`	`vox widget unpublish <widget-id>`

설치 코드가 필요하면 get --snippet을 실행하세요. 출력에는 public_id가 들어갑니다.

시작하기

빌드하기

배포하기

모니터링

기타

엔드포인트

요청과 응답 규격

생성, 게시, 조회

id와 public_id

상태 수명주기

설정 필드와 대시보드 항목

오류

CLI로 관리하기

관련 문서

​엔드포인트

​요청과 응답 규격

​생성, 게시, 조회

​id와 public_id

​상태 수명주기

​설정 필드와 대시보드 항목

​오류

​CLI로 관리하기

​관련 문서

엔드포인트

요청과 응답 규격

생성, 게시, 조회

id와 public_id

상태 수명주기

설정 필드와 대시보드 항목

오류

CLI로 관리하기

관련 문서