> ## 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 응답 요청

> API 채팅에 고객 메시지를 보내고, 그 결과로 생성된 도구 호출, 도구 결과, AI 에이전트 메시지를 순서대로 반환합니다. 메시지로 채팅이 종료되면 `output`에는 도구 호출과 도구 결과만 담길 수 있습니다. 메신저 채널의 채팅은 해당 채널에서 직접 고객 메시지를 받습니다.

같은 채팅에서 `client_idempotency_key`를 다시 보내면 AI 에이전트를 재실행하지 않습니다:
- 같은 본문, 처리 완료: 저장된 결과를 반환합니다.
- 같은 본문, 처리 중: 409 CHAT_TURN_IN_PROGRESS.
- 같은 본문, 실패: 409 CHAT_TURN_FAILED.
- 다른 본문: IDEMPOTENCY_KEY_CONFLICT로 거절합니다.

상담사가 채팅을 응대 중이거나 채널이 AI 응답을 허용하지 않으면 메시지만 저장하고 `reason`을 담은 202를 반환합니다.



## OpenAPI

````yaml /api-reference/v3/openapi.json post /chats/{chat_id}/messages
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}/messages:
    post:
      tags:
        - Chats
      summary: AI 응답 요청
      description: >-
        API 채팅에 고객 메시지를 보내고, 그 결과로 생성된 도구 호출, 도구 결과, AI 에이전트 메시지를 순서대로 반환합니다.
        메시지로 채팅이 종료되면 `output`에는 도구 호출과 도구 결과만 담길 수 있습니다. 메신저 채널의 채팅은 해당 채널에서 직접
        고객 메시지를 받습니다.


        같은 채팅에서 `client_idempotency_key`를 다시 보내면 AI 에이전트를 재실행하지 않습니다:

        - 같은 본문, 처리 완료: 저장된 결과를 반환합니다.

        - 같은 본문, 처리 중: 409 CHAT_TURN_IN_PROGRESS.

        - 같은 본문, 실패: 409 CHAT_TURN_FAILED.

        - 다른 본문: IDEMPOTENCY_KEY_CONFLICT로 거절합니다.


        상담사가 채팅을 응대 중이거나 채널이 AI 응답을 허용하지 않으면 메시지만 저장하고 `reason`을 담은 202를 반환합니다.
      operationId: sendChatMessage
      parameters:
        - name: chat_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Chat Id
            description: 채팅 ID입니다.
          description: 채팅 ID입니다.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatMessageRequest'
            examples:
              text:
                summary: 텍스트 메시지
                value:
                  text: 배송 상태를 알려주세요.
                  client_idempotency_key: message_001
              uploaded_image:
                summary: 업로드한 이미지와 텍스트
                value:
                  text: 이 사진의 상품을 확인해주세요.
                  images:
                    - type: file_key
                      file_key: file_abc123
                  client_idempotency_key: message_002
        description: AI 에이전트가 응답할 고객 메시지입니다.
      responses:
        '200':
          description: 성공 응답
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChatMessageResponse'
        '202':
          description: AI 에이전트가 답하지 않고 메시지만 저장했습니다. 이유는 `reason`에 있습니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChatMessageAcceptedResponse'
        '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
        '413':
          description: 요청 본문이 너무 큽니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                payloadTooLarge:
                  summary: 채팅 JSON 요청 본문이 10 MiB 제한을 초과함
                  value:
                    error:
                      code: PAYLOAD_TOO_LARGE
                      message: 요청 본문이 허용 크기를 초과했습니다.
                      details:
                        content_length: 11534336
                        max_bytes: 10485760
        '422':
          description: 요청 검증 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unprocessableEntity:
                  summary: 처리할 수 없는 요청입니다.
                  value:
                    error:
                      code: CONVERTED_FILE_TOO_LARGE
                      message: Converted image size exceeds the 1 MB limit.
                      details:
                        converted_size_bytes: 1258291
                        max_bytes: 1048576
        '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:
    CreateChatMessageRequest:
      anyOf:
        - properties:
            text:
              type: string
              minLength: 1
          required:
            - text
        - properties:
            images:
              type: array
              maxItems: 3
              minItems: 1
          required:
            - images
      properties:
        text:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: Text
          description: 고객 메시지 텍스트입니다.
        images:
          anyOf:
            - items:
                oneOf:
                  - $ref: '#/components/schemas/ChatMessageFileKeyImageInput'
                  - $ref: '#/components/schemas/ChatMessageBase64ImageInput'
                  - $ref: '#/components/schemas/ChatMessageUrlImageInput'
                discriminator:
                  propertyName: type
                  mapping:
                    base64: '#/components/schemas/ChatMessageBase64ImageInput'
                    file_key: '#/components/schemas/ChatMessageFileKeyImageInput'
                    url: '#/components/schemas/ChatMessageUrlImageInput'
              type: array
              maxItems: 3
              minItems: 1
            - type: 'null'
          title: Images
          description: 선택 이미지 입력입니다. 최대 3장까지 지원합니다.
        client_idempotency_key:
          type: string
          maxLength: 128
          minLength: 1
          title: Client Idempotency Key
          description: >-
            채팅 안에서 고객 메시지를 구분하는 멱등 키입니다. 같은 키와 같은 본문을 다시 보내면 AI 에이전트를 다시 실행하지 않고
            저장된 결과를 반환합니다. 그 메시지를 아직 처리 중이거나 처리에 실패했으면 409 오류를 반환합니다.
      type: object
      required:
        - client_idempotency_key
      title: CreateChatMessageRequest
    CreateChatMessageResponse:
      properties:
        chat_id:
          type: string
          format: uuid
          title: Chat Id
          description: 채팅 ID입니다.
        chat_status:
          $ref: '#/components/schemas/ChatStatusEnum'
          description: 응답 뒤의 채팅 상태입니다. `ended`면 이번 응답으로 채팅이 끝났습니다.
        input_message_id:
          type: integer
          title: Input Message Id
          description: AI 에이전트가 처리한 고객 메시지 ID입니다.
        output:
          items:
            oneOf:
              - $ref: '#/components/schemas/ChatTurnAgentMessageResponse'
              - $ref: '#/components/schemas/ChatToolCallInvocationResponse'
              - $ref: '#/components/schemas/ChatToolCallResultResponse'
            discriminator:
              propertyName: role
              mapping:
                agent: '#/components/schemas/ChatTurnAgentMessageResponse'
                tool_call_invocation: '#/components/schemas/ChatToolCallInvocationResponse'
                tool_call_result: '#/components/schemas/ChatToolCallResultResponse'
          type: array
          minItems: 1
          title: Output
          description: >-
            이번 메시지를 처리하며 나온 도구 호출, 도구 결과, AI 에이전트 메시지를 생성 순서대로 담습니다. 이 메시지로 채팅이
            끝났으면 AI 에이전트 메시지가 없을 수 있습니다.
      type: object
      required:
        - chat_id
        - chat_status
        - input_message_id
        - output
      title: CreateChatMessageResponse
    CreateChatMessageAcceptedResponse:
      properties:
        chat_id:
          type: string
          format: uuid
          title: Chat Id
          description: 채팅 ID입니다.
        chat_status:
          $ref: '#/components/schemas/ChatStatusEnum'
          description: 현재 채팅 상태입니다.
        reason:
          type: string
          enum:
            - operator_responding
            - agent_response_disabled
          title: Reason
          description: >-
            AI 에이전트가 답하지 않고 메시지만 저장한 이유입니다. `operator_responding`은 상담사가 응대 중,
            `agent_response_disabled`는 채널에서 AI 응답을 꺼 둔 상태입니다.
        input_message_id:
          type: integer
          title: Input Message Id
          description: 저장된 고객 메시지 ID입니다.
      type: object
      required:
        - chat_id
        - chat_status
        - reason
        - input_message_id
      title: CreateChatMessageAcceptedResponse
    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입니다.
    ChatMessageFileKeyImageInput:
      properties:
        type:
          type: string
          const: file_key
          title: Type
          description: 기존 업로드 파일 키를 사용하는 이미지 입력입니다.
        file_key:
          type: string
          minLength: 1
          title: File Key
          description: '`POST /files`에서 받은 기존 업로드 파일 키입니다.'
          examples:
            - file_abc123
      type: object
      required:
        - type
        - file_key
      title: ChatMessageFileKeyImageInput
    ChatMessageBase64ImageInput:
      properties:
        type:
          type: string
          const: base64
          title: Type
          description: base64 데이터를 직접 보내는 이미지 입력입니다.
        mime_type:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: Mime Type
          description: 클라이언트가 선언한 MIME 타입입니다.
          examples:
            - image/jpeg
        data:
          type: string
          minLength: 1
          title: Data
          description: base64 이미지 데이터입니다.
      type: object
      required:
        - type
        - data
      title: ChatMessageBase64ImageInput
    ChatMessageUrlImageInput:
      properties:
        type:
          type: string
          const: url
          title: Type
          description: vox.ai가 HTTPS URL에서 내려받는 이미지 입력입니다.
        url:
          type: string
          minLength: 1
          title: Url
          description: vox.ai가 내려받을 HTTPS 이미지 URL입니다.
          examples:
            - https://example.com/photo.jpg
      type: object
      required:
        - type
        - url
      title: ChatMessageUrlImageInput
    ChatStatusEnum:
      type: string
      enum:
        - active
        - ended
      title: ChatStatusEnum
    ChatTurnAgentMessageResponse:
      properties:
        id:
          type: integer
          title: Id
          description: 채팅 메시지 ID입니다.
        role:
          type: string
          const: agent
          title: Role
          description: 에이전트 메시지 역할입니다.
        content:
          type: string
          minLength: 1
          title: Content
          description: 이번 응답에서 AI 에이전트가 보낸 메시지입니다.
        created_at:
          type: integer
          title: Created At
          description: 리소스 생성 시각입니다. unix milliseconds 형식입니다.
        attachments:
          anyOf:
            - items:
                $ref: '#/components/schemas/ChatMessageAttachment'
              type: array
            - type: 'null'
          title: Attachments
          description: API 채널의 이미지 첨부 목록입니다. file_key, base64, url 입력을 지원합니다.
        client_idempotency_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Idempotency Key
          description: >-
            이 메시지를 저장한 요청의 `client_idempotency_key`입니다. API와 위젯 채널로 보낸 고객 메시지에만
            있으며, 응답을 받지 못한 전송을 조회 결과와 대조하는 데 씁니다.
        status:
          anyOf:
            - type: string
              enum:
                - received
                - failed
            - type: 'null'
          title: Status
          description: >-
            고객 메시지의 처리 결과입니다. failed는 AI 응답이 끝내 실패함, received는 그 밖의 고객 메시지입니다.
            고객 메시지가 아니면 null입니다.
        error:
          anyOf:
            - $ref: '#/components/schemas/ChatMessageError'
            - type: 'null'
          description: status가 failed일 때 실패 이유입니다. 그 밖에는 null입니다.
        delivery:
          anyOf:
            - $ref: '#/components/schemas/ChatTranscriptDeliveryResponse'
            - type: 'null'
          description: >-
            채널로 내보낸 메시지의 발신 결과입니다. 고객 메시지와 API·위젯 채팅의 메시지처럼 채널로 내보내지 않은 메시지는
            null입니다.
        content_errors:
          anyOf:
            - items:
                $ref: '#/components/schemas/ChatMessageContentError'
              type: array
            - type: 'null'
          title: Content Errors
          description: >-
            고객이 보낸 것 가운데 채널이 받지 못한 부분입니다. content에는 고객 글 뒤에 항목마다 안내 한 줄이 붙습니다.
            받은 첨부는 attachments에 그대로 있고, 받지 못한 것이 없으면 null입니다.
      type: object
      required:
        - id
        - role
        - content
        - created_at
        - attachments
      title: ChatTurnAgentMessageResponse
    ChatToolCallInvocationResponse:
      properties:
        id:
          type: integer
          title: Id
          description: 도구 호출이 저장된 채팅 메시지 ID입니다.
        role:
          type: string
          const: tool_call_invocation
          title: Role
          description: 도구 호출 항목 역할입니다.
        tool_call_id:
          type: string
          title: Tool Call Id
          description: 도구 호출 식별자입니다.
        name:
          type: string
          title: Name
          description: 호출된 도구 이름입니다.
        arguments:
          additionalProperties: true
          type: object
          title: Arguments
          description: 도구 호출 인자입니다.
        created_at:
          type: integer
          title: Created At
          description: 리소스 생성 시각입니다. unix milliseconds 형식입니다.
      type: object
      required:
        - id
        - role
        - tool_call_id
        - name
        - arguments
        - created_at
      title: ChatToolCallInvocationResponse
    ChatToolCallResultResponse:
      properties:
        id:
          type: integer
          title: Id
          description: 도구 결과가 저장된 채팅 메시지 ID입니다.
        role:
          type: string
          const: tool_call_result
          title: Role
          description: 도구 호출 결과 항목 역할입니다.
        tool_call_id:
          type: string
          title: Tool Call Id
          description: 대응하는 도구 호출 식별자입니다.
        content:
          type: string
          title: Content
          description: 도구 호출 결과 텍스트입니다.
        success:
          type: boolean
          title: Success
          description: 도구 실행 오류가 기록되지 않았으면 true, 기록되었으면 false입니다.
          default: true
        status_code:
          anyOf:
            - type: integer
            - type: 'null'
          title: Status Code
          description: 채팅의 도구 결과에는 응답 상태 코드를 기록하지 않으므로 null입니다.
        created_at:
          type: integer
          title: Created At
          description: 리소스 생성 시각입니다. unix milliseconds 형식입니다.
      type: object
      required:
        - id
        - role
        - tool_call_id
        - content
        - created_at
      title: ChatToolCallResultResponse
    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`를 포함합니다.
    ChatMessageAttachment:
      properties:
        file_key:
          type: string
          title: File Key
          description: 첨부 파일 키입니다.
        mime_type:
          type: string
          title: Mime Type
          description: 첨부 MIME 타입입니다.
      type: object
      required:
        - file_key
        - mime_type
      title: ChatMessageAttachment
    ChatMessageError:
      properties:
        code:
          type: string
          enum:
            - AI_UNAVAILABLE
            - AI_ERROR
            - AI_TIMEOUT
            - AI_REJECTED
          title: Code
          description: >-
            고객 메시지에 AI 에이전트가 끝내 답하지 못한 이유입니다. AI_UNAVAILABLE은 연결 실패, AI_ERROR는
            응답 생성 실패, AI_TIMEOUT은 응답 시간 초과, AI_REJECTED는 요청 거절입니다.
        message:
          type: string
          title: Message
          description: 사람이 읽는 설명입니다. 문구는 바뀔 수 있습니다.
      type: object
      required:
        - code
        - message
      title: ChatMessageError
    ChatTranscriptDeliveryResponse:
      properties:
        status:
          type: string
          enum:
            - pending
            - sent
            - failed
            - unknown
          title: Status
          description: >-
            채널 발신 상태입니다. pending은 발신 결과를 기다리는 중, sent는 채널이 받았음, failed는 발신 실패,
            unknown은 결과를 확인할 수 없어 다시 보내지 않은 상태입니다.
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: 발신이 실패했거나 결과를 확인할 수 없을 때의 기계 판독용 에러 코드입니다. 그 밖에는 null입니다.
      type: object
      required:
        - status
      title: ChatTranscriptDeliveryResponse
    ChatMessageContentError:
      properties:
        code:
          type: string
          enum:
            - UNSUPPORTED_TYPE
            - TOO_LARGE
            - UNSUPPORTED_FORMAT
            - UNAVAILABLE
            - LIMIT_EXCEEDED
            - TEXT_TOO_LONG
          title: Code
          description: >-
            고객이 보낸 것을 받지 못한 이유입니다. UNSUPPORTED_TYPE은 이 채널이 받지 않는 종류(스티커, 위치,
            연락처, 동영상·음성·파일, 텍스트 전용 채널의 이미지), TOO_LARGE는 용량·해상도·프레임 수가 한도를 넘음,
            UNSUPPORTED_FORMAT은 지원하지 않는 파일 형식, UNAVAILABLE은 내려받기나 변환에 실패함,
            LIMIT_EXCEEDED는 메시지당 개수 한도를 넘은 부분, TEXT_TOO_LONG은 채널 글자 수 한도를 넘어
            앞부분만 받음입니다.
        type:
          type: string
          enum:
            - image
            - video
            - audio
            - file
            - sticker
            - location
            - contact
            - text
            - other
          title: Type
          description: 받지 못한 것의 종류입니다.
        count:
          type: integer
          title: Count
          description: 같은 code와 type으로 받지 못한 개수입니다.
        message:
          type: string
          title: Message
          description: 사람이 읽는 설명입니다. 문구는 바뀔 수 있으니 code와 type으로 분기하세요.
      type: object
      required:
        - code
        - type
        - count
        - message
      title: ChatMessageContentError
  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.