API와 CLI

대시보드의 배포 > 위젯에서 다루는 위젯을 v3 API와 vox CLI로도 만들고, 수정하고, 게시할 수 있어요. 전체 파라미터는 API 레퍼런스 소개의 위젯 그룹에 있어요.

엔드포인트

모든 관리 작업은 /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`	게시를 해제해요.

요청과 응답 규격

구분	계약
만들기 요청	`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는 만들기나 수정 요청으로 바꿀 수 없어요.

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`

요청 예시

만들기, 게시, 조회 순서로 호출하세요. API 키는 $VOX_API_KEY 환경 변수에 두었다고 가정해요.

위젯 만들기

POST /v3/widgets로 초안을 만들어요. agent.agent_id와 allowed_domains를 넣으세요. 응답의 status는 draft이고, public_id는 wgt_로 시작하며, published_version_id는 null이에요.

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

{
  "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를 넣으세요. 응답의 status는 published이고 published_version_id에 UUID가 들어가요.

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

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

조회하기

게시한 위젯을 확인해요. 응답의 status, public_id, published_version_id는 게시 결과와 같아요.

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

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

오류

상태 코드	조건	처리 방법
`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>`와 `create`의 선택 플래그. 한 개 이상 필요해요. `--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 명령

관련 문서