> ## 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. # 상담사 통화 조회 > 상담사 통화 한 건을 조회합니다. 전체 사람 상담 대화록, 사용 가능한 경우 15분 동안 유효한 서명된 녹음 URL, 상담사 통화 비용을 포함합니다. ## OpenAPI ````yaml /api-reference/v3/openapi.json get /operator-calls/{operator_call_id} openapi: 3.1.0 info: title: vox.ai API description: > vox.ai API v3 ### v3 공개 계약 규칙 - 인증은 `Authorization: Bearer ` 헤더를 사용합니다. 조직 API 키를 Bearer 토큰으로 전달합니다. - 요청과 응답 필드는 기본적으로 `snake_case`를 사용합니다. - `agent.data`는 에이전트 레지스트리와 호환되어야 하므로 `callSettings`, `toolIds`, `builtInTools`, `presetDynamicVariables` 같은 camelCase 필드를 유지합니다. - `_at`으로 끝나는 타임스탬프는 unix milliseconds입니다. 일부 입력값은 호환성을 위해 10~11자리 unix seconds도 허용하고 milliseconds로 정규화합니다. - 캠페인 통화 가능 시간은 분 단위 정수(`start_min` / `end_min`)를 사용합니다. 알림 스케줄은 `HH:MM` 문자열(`start_time` / `end_time`)을 사용합니다. - 응답 객체 자신의 식별자는 `id`입니다. 다른 리소스를 참조하는 필드와 path parameter는 `agent_id`, `call_id`, `telephone_line_id`처럼 명시적인 이름을 사용합니다. - 실패 응답은 `{ "error": { "code", "message", "details" } }` 형태입니다. 가능한 경우 `details.field`, `details.reason`, `details.allowed_values`를 함께 제공합니다. version: 3.0.0 servers: - url: https://client-api.tryvox.co/v3 description: 운영 security: [] paths: /operator-calls/{operator_call_id}: get: tags: - Operator Calls summary: 상담사 통화 조회 description: >- 상담사 통화 한 건을 조회합니다. 전체 사람 상담 대화록, 사용 가능한 경우 15분 동안 유효한 서명된 녹음 URL, 상담사 통화 비용을 포함합니다. operationId: getOperatorCall parameters: - name: operator_call_id in: path required: true schema: type: string format: uuid title: Operator Call Id description: 상담사 통화 ID입니다. description: 상담사 통화 ID입니다. responses: '200': description: 성공 응답 content: application/json: schema: $ref: '#/components/schemas/OperatorCallDetailResponse' '400': description: 요청 검증에 실패했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: 요청 검증 오류 value: error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank '401': description: 인증이 필요합니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Bearer 토큰 누락 또는 오류 value: error: code: UNAUTHORIZED message: Authentication is required. details: {} '403': description: 권한이 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: 권한 없음 value: error: code: FORBIDDEN message: Permission denied. details: {} '404': description: 리소스를 찾을 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: 상담사 통화를 찾을 수 없음 value: error: code: OPERATOR_CALL_NOT_FOUND message: operator call를 찾을 수 없습니다. details: operator_call_id: 77777777-7777-4777-8777-777777777777 '409': description: 충돌이 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conflict: summary: 상태 충돌 value: error: code: CONFLICT message: The requested operation conflicts with current state. details: current_status: draft '429': description: >- 요청 한도를 초과했습니다. API 키 트래픽의 기본 한도는 조직당 초당 5건과 분당 120건입니다. Supabase JWT 트래픽의 기본 한도는 사용자당 초당 10건과 분당 240건이며, 조직 대시보드에는 분당 2,400건의 기본 보조 한도가 적용됩니다. 운영자가 한도를 변경할 수 있습니다. 초과한 버킷에 적용된 한도와 기간은 429 응답의 `X-RateLimit-Limit` 및 `X-RateLimit-Window` 헤더로 알립니다. 개별 경로의 자체 제한기가 생성한 429 응답에는 이 헤더가 없을 수 있습니다. headers: Retry-After: description: >- 초과한 공용 v3 인증 주체 제한기의 기간이 초기화될 때까지 남은 초입니다. 개별 경로의 자체 제한기가 생성한 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 X-RateLimit-Limit: description: >- 초과한 공용 v3 인증 주체 제한기 기간의 최대 요청 수입니다. 개별 경로의 자체 제한기가 생성한 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 X-RateLimit-Window: description: >- 초과한 공용 v3 인증 주체 제한기 기간의 길이입니다. 단위는 초입니다. 개별 경로의 자체 제한기가 생성한 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: 요청 한도 초과 value: error: code: RATE_LIMIT_EXCEEDED message: Too many requests. details: limit: 10 window_seconds: 1 scope: user '500': description: 서버 내부 오류가 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: 서버 내부 오류 value: error: code: INTERNAL_ERROR message: Internal server error. details: {} '503': description: 서비스를 일시적으로 사용할 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serviceUnavailable: summary: 서비스 일시 사용 불가 value: error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. details: {} recordingStoreUnavailable: summary: 녹음 URL 서명기를 일시적으로 사용할 수 없음 value: error: code: RECORDING_STORE_UNAVAILABLE message: 녹음 저장소가 준비되지 않았습니다. details: retryable: true security: - BearerAuth: [] components: schemas: OperatorCallDetailResponse: properties: id: type: string format: uuid title: Id description: operator call 고유 식별자. call_id: anyOf: - type: string format: uuid - type: 'null' title: Call Id description: 선행 AI call id. standalone operator call이면 null. customer_id: anyOf: - type: string format: uuid - type: 'null' title: Customer Id description: 연결된 고객의 고유 식별자. agent: anyOf: - $ref: '#/components/schemas/OperatorCallAgentMapping' - type: 'null' description: 선행 AI 통화의 에이전트 매핑입니다. standalone이거나 선행 통화의 매핑을 확인할 수 없으면 null입니다. call_type: $ref: '#/components/schemas/OperatorCallType' description: >- 상담사 기준 통화 시작 방향. 기존 AI call이 상담사에게 전달되면 inbound, 상담사가 직접 발신하면 outbound입니다. from_number: anyOf: - type: string - type: 'null' title: From Number description: 발신 번호. to_number: anyOf: - type: string - type: 'null' title: To Number description: 수신(고객) 번호. presentation_number: anyOf: - type: string - type: 'null' title: Presentation Number description: 발신 표시 번호. operator: $ref: '#/components/schemas/OperatorCallOperatorRef' description: 담당 operator. status: $ref: '#/components/schemas/OperatorCallStatus' description: operator call lifecycle 상태. 값별 의미와 전이는 enum 정의를 참조합니다. disconnection_reason: anyOf: - $ref: '#/components/schemas/OperatorCallDisconnectionReason' - type: 'null' description: operator call 종료 사유. 진행 중이거나 미등록 내부 사유면 null. requested_at: type: integer title: Requested At description: operator call 요청/행 생성 시각 (unix ms). answered_at: anyOf: - type: integer - type: 'null' title: Answered At description: PSTN 응답 시각 (unix ms). start_at: anyOf: - type: integer - type: 'null' title: Start At description: 사람 구간 시작 시각 (unix ms). end_at: anyOf: - type: integer - type: 'null' title: End At description: 사람 구간 종료 시각 (unix ms). opt_out_sensitive_data_storage: anyOf: - type: boolean - type: 'null' title: Opt Out Sensitive Data Storage description: >- 현재 응답에 적용된 effective storage opt-out. takeover는 조회 시점 parent AI call 정책에서 파생하며, parent 소유를 증명할 수 없으면 null. transcript: anyOf: - items: $ref: '#/components/schemas/OperatorCallTranscriptItem' type: array - type: 'null' title: Transcript description: >- 사람 상담 구간 전체 대화록. 발생 시각 오름차순. 실제 발화가 없으면 빈 배열이고, privacy 또는 parent 소유 미증명으로 공개할 수 없으면 null. recording_url: anyOf: - type: string - type: 'null' title: Recording Url description: >- 사람 상담 구간 녹음 URL. finalized 녹음은 15분 signed URL이며, 녹음 없음·미완료·옵트아웃이면 null. recording_offset_ms: anyOf: - type: integer - type: 'null' title: Recording Offset Ms description: 물리 콜 녹음 시작 대비 사람 상담 구간 시작 오프셋 (ms). call_cost: anyOf: - $ref: '#/components/schemas/OperatorCallCost' - type: 'null' description: operator call 비용. 과금 데이터가 아직 없으면 null. type: object required: - id - agent - call_type - operator - status - requested_at - opt_out_sensitive_data_storage title: OperatorCallDetailResponse ErrorResponse: type: object required: - error title: ErrorResponse description: 모든 실패 응답에서 사용하는 v3 error envelope입니다. examples: - error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: error: $ref: '#/components/schemas/ErrorDetail' description: 오류 payload입니다. OperatorCallAgentMapping: properties: agent_id: description: 에이전트 UUID입니다. format: uuid title: Agent Id type: string agent_version: type: string title: Agent Version description: >- 에이전트 버전. 허용값: "current", "production", 또는 "v{n}" (n≥1). operator-call 응답의 agent 객체가 존재하면 반드시 포함됩니다. pattern: ^(current|production|v[1-9][0-9]*)$ examples: - current - production - v1 additionalProperties: false type: object required: - agent_id - agent_version title: OperatorCallAgentMapping description: 상담사 통화 응답에 포함되는 완전한 에이전트 매핑입니다. OperatorCallType: type: string enum: - inbound - outbound title: OperatorCallType OperatorCallOperatorRef: properties: member_id: anyOf: - type: string format: uuid - type: 'null' title: Member Id description: 조직 멤버 id. API-key claim이면 null. name: anyOf: - type: string - type: 'null' title: Name description: operator 표시 이름. external_id: anyOf: - type: string - type: 'null' title: External Id description: 호출자 시스템의 operator 식별자. additionalProperties: false type: object title: OperatorCallOperatorRef OperatorCallStatus: type: string enum: - connecting - operator_ready - dialing - ongoing - ending - ended - failed title: OperatorCallStatus description: >- 공개 lifecycle입니다. 이어받기(takeover): connecting -> ongoing -> ending -> ended. 직접 발신(standalone): connecting -> operator_ready -> dialing -> ongoing -> ending -> ended. 종료 전 상태는 언제든 failed로 전이될 수 있습니다. OperatorCallDisconnectionReason: type: string enum: - operator_hangup - user_hangup - dial_failed - dial_no_answer - dial_busy - orphaned_no_agent_pickup - error_voxai - system_hangup title: OperatorCallDisconnectionReason OperatorCallTranscriptItem: properties: role: type: string enum: - operator - user - system title: Role description: 발화 주체. operator(상담사), user(고객), system(시스템 안내). content: type: string title: Content description: 발화 텍스트입니다. start_at: type: integer title: Start At description: 발화 시각 (unix ms). recording_start_offset_ms: anyOf: - type: integer minimum: 0 - type: 'null' title: Recording Start Offset Ms description: 사람 상담 구간 녹음 파일 내 이 발화의 시작 오프셋 (ms). 녹음이 없으면 null. recording_end_offset_ms: anyOf: - type: integer minimum: 0 - type: 'null' title: Recording End Offset Ms description: 사람 상담 구간 녹음 파일 내 이 발화의 종료 오프셋 (ms). 녹음이 없으면 null. type: object required: - role - content - start_at title: OperatorCallTranscriptItem OperatorCallCost: properties: total_cost: type: string title: Total Cost description: operator call 총 비용(KRW 원 단위, Decimal 문자열). breakdown: $ref: '#/components/schemas/OperatorCallCostBreakdown' type: object required: - total_cost - breakdown title: OperatorCallCost ErrorDetail: type: object required: - code - message - details title: ErrorDetail description: 기계가 읽을 수 있는 v3 오류 상세 정보입니다. examples: - code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: code: type: string title: Code description: 기계가 읽을 수 있는 오류 code입니다. message parsing 대신 이 값을 사용합니다. examples: - VALIDATION_ERROR message: type: string title: Message description: 사용자에게 표시할 수 있는 오류 메시지입니다. 프로그램 처리는 `code`를 사용합니다. examples: - Request validation failed. details: type: object title: Details additionalProperties: true description: 구조화된 context입니다. 주로 `field`, `reason`, `allowed_values`를 포함합니다. OperatorCallCostBreakdown: properties: takeover_fee: anyOf: - $ref: '#/components/schemas/OperatorCallFeeBlock' - type: 'null' description: AI call에서 사람에게 넘긴 구간의 비용. outbound_fee: anyOf: - $ref: '#/components/schemas/OperatorCallFeeBlock' - type: 'null' description: standalone operator 발신 비용. type: object title: OperatorCallCostBreakdown OperatorCallFeeBlock: properties: duration_ms: anyOf: - type: integer - type: 'null' title: Duration Ms description: 실제 사람 상담 구간 길이 (ms). billsec: anyOf: - type: integer - type: 'null' title: Billsec description: 요금 증분 단위로 올림한 과금 시간 (초). rate: anyOf: - type: string - type: 'null' title: Rate description: 설정된 요금 증분 1단위당 KRW Decimal 문자열. amount: anyOf: - type: string - type: 'null' title: Amount description: 해당 비용 구간의 KRW Decimal 문자열. type: object title: OperatorCallFeeBlock securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Organization API key description: '조직 API 키를 `Authorization: Bearer ` 형식으로 보냅니다.' ````