> ## 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.

# 상담사 이어받기

> AI 에이전트가 응대하던 채팅을 상담사가 이어받습니다. AI 에이전트는 더 답하지 않으며, 고객 메시지는 답장 없이 저장됩니다. 상담사 답장은 `POST /chats/{chat_id}/outbound-messages`에 `origin=operator`로 보냅니다. 워크스페이스 API 키는 상담사를 배정하지 않고 채팅을 이어받습니다. 채팅이 이미 그 상태라면 변경 없이 요청이 성공합니다. 상담사가 배정된 채팅은 409 CHAT_RESPONDER_CONFLICT로 거절합니다. 응답에 바뀐 `responder`를 담으며, 고객에게는 알리지 않습니다.



## OpenAPI

````yaml /api-reference/v3/openapi.json post /chats/{chat_id}/takeover
openapi: 3.1.0
info:
  title: vox.ai API
  description: >
    vox.ai API v3


    ### v3 공개 계약 규칙


    - 인증은 `Authorization: Bearer <token>` 헤더를 사용합니다. 워크스페이스 API 키를 Bearer 토큰으로
    전달합니다.

    - 요청과 응답 필드는 기본적으로 `snake_case`를 사용합니다.

    - 에이전트 `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:
  /chats/{chat_id}/takeover:
    post:
      tags:
        - Chats
      summary: 상담사 이어받기
      description: >-
        AI 에이전트가 응대하던 채팅을 상담사가 이어받습니다. AI 에이전트는 더 답하지 않으며, 고객 메시지는 답장 없이 저장됩니다.
        상담사 답장은 `POST /chats/{chat_id}/outbound-messages`에 `origin=operator`로
        보냅니다. 워크스페이스 API 키는 상담사를 배정하지 않고 채팅을 이어받습니다. 채팅이 이미 그 상태라면 변경 없이 요청이
        성공합니다. 상담사가 배정된 채팅은 409 CHAT_RESPONDER_CONFLICT로 거절합니다. 응답에 바뀐
        `responder`를 담으며, 고객에게는 알리지 않습니다.
      operationId: takeoverChat
      parameters:
        - name: chat_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Chat Id
            description: 채팅 ID입니다.
          description: 채팅 ID입니다.
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            description: >-
              상태를 변경하는 POST 요청에 필요한 멱등성 키입니다. 24시간 동안 안전하게 재시도할 때 사용합니다. 값은 비어
              있으면 안 됩니다. 최대 255자까지 허용합니다.
            minLength: 1
            maxLength: 255
            title: Idempotency-Key
          description: >-
            중복 실행 방지를 위한 필수 키입니다. 중복 요청 방지는 24시간 유지되지만, 기존 200 응답 재전송은 응답 기록 보존
            기간에 한정되며 워크스페이스의 대화 기록 보존 정책에 따라 더 일찍 삭제될 수 있습니다.
        - name: X-Vox-Organization-Id
          in: header
          required: false
          description: API 키로 인증하면 보내지 않아도 됩니다. 그 키의 워크스페이스를 사용합니다.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 성공 응답
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponderCommandResponse'
        '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: CHAT_NOT_FOUND
                      message: 채팅을 찾을 수 없습니다.
                      details:
                        chat_id: 22222222-2222-4222-8222-222222222222
        '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회입니다. 이 공용 한도로 인한 429 응답에는 X-RateLimit-Limit,
            X-RateLimit-Window, Retry-After 헤더가 포함됩니다. 개별 엔드포인트 한도에서는 이 헤더 중 일부
            또는 전체가 생략될 수 있습니다.
          headers:
            Retry-After:
              description: 재시도하기 전에 기다려야 하는 시간입니다. 단위는 초입니다.
              schema:
                type: integer
                minimum: 1
            X-RateLimit-Limit:
              description: 윈도우 동안 허용되는 최대 요청 수입니다.
              schema:
                type: integer
                minimum: 1
            X-RateLimit-Window:
              description: 윈도우 길이입니다. 단위는 초입니다.
              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: 5
                        window_seconds: 1
                        scope: org
        '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: {}
      security:
        - BearerAuth: []
components:
  schemas:
    ChatResponderCommandResponse:
      properties:
        chat_id:
          type: string
          format: uuid
          title: Chat Id
          description: 채팅 ID입니다.
        status:
          $ref: '#/components/schemas/ChatStatusEnum'
          description: 현재 채팅 상태입니다.
        channel:
          type: string
          title: Channel
          description: 채팅 채널입니다.
        responder:
          $ref: '#/components/schemas/ChatResponderResponse'
          description: 요청 뒤의 응답 담당입니다.
      type: object
      required:
        - chat_id
        - status
        - channel
        - responder
      title: ChatResponderCommandResponse
    ErrorResponse:
      type: object
      required:
        - error
      title: ErrorResponse
      description: 모든 실패 요청에서 반환되는 오류 본문입니다.
      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입니다.
    ChatStatusEnum:
      type: string
      enum:
        - active
        - ended
      title: ChatStatusEnum
    ChatResponderResponse:
      properties:
        type:
          type: string
          enum:
            - agent
            - operator
          title: Type
          description: >-
            지금 고객에게 답하는 응답 담당입니다. `agent`는 AI 에이전트, `operator`는 상담사이며 API로 이어받은
            채팅도 `operator`입니다.
        operator:
          anyOf:
            - $ref: '#/components/schemas/ChatResponderOperatorResponse'
            - type: 'null'
          description: vox.ai에 등록된 상담사가 응대 중일 때 그 상담사 정보입니다. 그 밖에는 null입니다.
        changed_at:
          type: integer
          title: Changed At
          description: 응답 담당이 지금 값으로 바뀐 시각입니다(unix ms).
      type: object
      required:
        - type
        - operator
        - changed_at
      title: ChatResponderResponse
    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`를 포함합니다.
    ChatResponderOperatorResponse:
      properties:
        member_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Member Id
          description: 현재 응대 중인 상담사의 워크스페이스 멤버 ID입니다.
      type: object
      required:
        - member_id
      title: ChatResponderOperatorResponse
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Organization API key
      description: '워크스페이스 API 키를 `Authorization: Bearer <token>` 형식으로 보냅니다.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.