Skip to main content
vox.ai v3 API는 음성·채팅 AI 에이전트의 전체 라이프사이클을 코드로 다루는 REST API예요. v2보다 컨벤션이 일관되고 에러 모델이 명시적이며, 스키마 레지스트리와 OpenAPI로 지금 계약을 직접 확인할 수 있어요.

​
Base URL

​
인증

모든 요청에 Authorization: Bearer <token> 헤더가 필요해요. 토큰은 대시보드 설정에서 발급한 워크스페이스(organization_id) API 키를 쓰세요.

​
컨벤션

  • snake_case: 요청·응답 필드는 기본으로 snake_case를 써요. agent.data와 flow.nodes[].data 아래는 에이전트 설정과 노드별 설정을 그대로 담으려고 일부 camelCase를 유지해요.
  • 플로우 작성과 검증: 플로우 에이전트 그래프는 flow 필드로 작성하고, 저장하기 전에 POST /agents/validate-flow로 검증할 수 있어요. flow_data는 기존 빌더 호환용 필드라 새 통합에서는 쓰지 않는 편이 좋아요. 작성법은 API로 플로우 작성 및 검증에 있어요.
  • 밀리초 타임스탬프: _at으로 끝나는 타임스탬프 필드는 unix milliseconds예요.
  • 커서 페이지네이션: list 엔드포인트는 cursor와 limit(1~100)을 써요. 다음 페이지는 응답의 next_cursor를 그대로 다시 넘기세요.
  • 명시적 식별자: 응답 객체 자신의 ID는 id예요. 다른 리소스 참조는 agent_id, call_id처럼 이름을 밝혀 써요.
  • 에러 엔벨로프: 모든 실패 응답은 { "error": { "code", "message", "details" } } 꼴이에요. 제어 흐름은 code로 나누세요.
  • Rate limit: 모든 v3 엔드포인트는 워크스페이스 단위 rate limit(초당 5회, 분당 120회)을 함께 써요. 넘으면 429와 RATE_LIMIT_EXCEEDED 코드를 돌려줘요.
  • 음성 런타임: 새로 만들 때 agent.data.runtime을 생략하거나 { "type": "pipeline" }으로 보내면 기존 파이프라인을 써요. 수정할 때 runtime을 생략하면 지금 런타임을 유지해요. GPT-Live, Grok Voice, Gemini Live는 지금 type: "single_prompt"에서만 지원하고 플로우 에이전트에서는 거부돼요. 작성 규칙은 실시간 음성 런타임 API 작성에 있어요.
  • 대시보드 용어 대응: 대시보드의 대량 발신은 API에서 campaign이고, 문자 대량 발신은 sms_batch예요. 경로·필드·이벤트 이름은 영문 그대로 써요.

​
주요 리소스

  • 에이전트: 음성 에이전트(single prompt, flow)와 버전을 만들고 수정하고 게시해요.
  • 모델: 에이전트에 쓸 수 있는 LLM과 음성 모델을 조회하고 관리해요.
  • 도구: 에이전트가 호출할 API 도구를 만들고 실행 설정을 관리해요.
  • 지식 베이스: 에이전트가 참조할 지식 베이스와 원본 문서를 관리해요.
  • 스키마: agent.data, 플로우와 도구의 공개 JSON Schema를 조회해요.
  • 전화번호: 번호 구매·등록, 에이전트 매핑, SIP 트렁크를 관리해요.
  • 통화·대량 발신·SMS: 통화 한 건과 대량 발신(campaign)을 실행하고 조회해요. SMS는 발신·수신 목록과 단건 상세를 조회해요.
  • 고객·메모리: 고객 식별자와 고객 속성, 대화에서 추출한 메모리를 관리해요.
  • 알림: 통화 지표를 감시할 알림 규칙과 인시던트를 관리해요.

​
스키마 레지스트리

v3는 에이전트 작성에 필요한 JSON Schema를 API와 OpenAPI로 열어 둬요. 클라이언트는 스키마를 하드코딩하지 않고 지금 계약을 확인해 쓸 수 있어요.
  • GET /schemas: 쓸 수 있는 스키마 목록(agent-schema, flow-schema, tool-schema 등)을 조회해요.
  • GET /schemas/{namespace}/{schema_type}: 특정 스키마 본문을 조회해요.
  • GET /schemas?category=agent-authoring&include_schema=true: 에이전트 작성에 필요한 레지스트리 스키마를 함께 조회해요.

​
에이전트 data 수정

PATCH /agents/{agent_id}에는 GET /agents/{agent_id}?version=current에서 확인한 head_revision을 expected_head_revision으로 넘기세요. 플로우 그래프를 바꿀 때는 같은 응답의 flow_revision도 expected_flow_revision으로 보내세요. 오래된 revision은 REVISION_CONFLICT로 거부되니, 클라이언트가 최신 상태를 자동으로 다시 읽어 그대로 재시도(blind retry)하지 않게 하세요. data는 부분 수정 payload예요. 생략한 하위 설정은 기존 값을 유지하고, 일반 객체는 한 단계 병합하며 배열은 통째로 바꿔요. data.runtime, data.manuals, data.presetDynamicVariables는 원자적으로 통째로 바꿔요. data.builtInTools를 넣으면 기본 도구 배열도 통째로 바꿔요.
  • builtInTools 생략: 기존 기본 도구 유지
  • builtInTools: []: 기본 도구 전체 제거
  • builtInTools: null: 잘못된 요청
  • runtime 생략: 지금 런타임 유지
  • runtime 전송: 런타임 객체 전체 교체
  • manuals 전송: 에이전트 소유 메뉴얼 맵 전체 교체
전역 /manuals API는 없어요. 메뉴얼을 읽거나 고치려면 /agents/{agent_id}/manuals 하위 경로를 쓰세요. 아래처럼 기본값이 아닌 tool-level 설정은 기존 도구 객체에서 유지해야 해요. 프롬프트만 바꿀 때는 builtInTools를 보내지 않거나, GET /agents/{agent_id}에서 받은 도구 객체를 그대로 두고 필요한 필드만 바꾸세요. 정확한 필드 구조는 GET /schemas/tool-schema/{schema_type}로 확인하세요.

​
네이티브 실시간 런타임

GPT-Live, Grok Voice, Gemini Live의 음성 설정은 data.runtime.voice에 둬요. 기존 파이프라인의 data.voice·data.stt·data.parallelSTT와 현재 스키마에서 호환되지 않는 speech preference를 네이티브 실시간 요청에 복사하지 마세요. data.speech 전체를 짐작으로 지우지 말고 현재 agent schema를 따르세요. 새 네이티브 실시간 에이전트를 만들 때는 고를 수 있는 data.llm.model이 필요하고, chatLlm 필드나 data.llm의 암묵적인 모델 매핑은 쓰지 않아요. GPT-Live, Grok Voice, Gemini Live는 유효한 data.speech.isAllowInterruption 값이 true여야 해요. 만들 때 값을 생략하면 기본값 true를 쓰지만, PATCH에서 생략하면 지금 값을 유지해요. 그래서 기존 값이 false인 에이전트를 전환할 때는 true를 명시하세요. API는 이 값을 자동으로 바꾸지 않아요. 세 런타임은 type: "single_prompt" 전용이에요. 기존 type: "flow" 에이전트는 pipeline 런타임을 쓰고, 자동으로 변환하거나 마이그레이션하지 않아요. flow.nodes[].data.llm은 기존 플로우 설정으로 보존하지만 네이티브 실시간 기능으로 해석하지 않아요. 새 에이전트를 만들 때 data.runtime을 생략하거나 type: "pipeline"으로 보내면 기존 파이프라인 동작을 써요. PATCH에서 runtime을 생략하면 지금 런타임을 유지해요. 파이프라인으로 되돌릴 때는 runtime: { "type": "pipeline" }과 함께 stt, voice를 명시하세요. 세 네이티브 실시간 런타임은 provider 전용 model과 음성을 명시해야 해요. GPT-Live는 빌트인이나 커스텀 음성을, Grok Voice와 Gemini Live는 빌트인 음성만 받아요. Grok Voice는 grok-voice-think-fast-2.0, Gemini Live는 초기 1.8.1 호환 계약의 gemini-2.5-flash-native-audio-preview-12-2025를 써요. Gemini 3.1과 3.8은 지원하지 않아요. Grok Voice와 Gemini Live는 custom 음성을 거부해요. custom 참조는 새 GPT-Live 커스텀 음성에만 쓰고, 기존 pipeline 음성은 그대로 유지해요. GPT-Live custom reference만으로 OpenAI 권한·프로비저닝이나 품질 검증을 마친 것은 아니에요.

​
관련 문서