> ## 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. # 채팅 생성 > 프롬프트 또는 플로우 에이전트로 API 채팅을 생성합니다. 저장된 첫 대화 내역을 함께 반환합니다. ## OpenAPI ````yaml /api-reference/v3/openapi.json post /chats 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: /chats: post: tags: - Chats summary: 채팅 생성 description: 프롬프트 또는 플로우 에이전트로 API 채팅을 생성합니다. 저장된 첫 대화 내역을 함께 반환합니다. operationId: createChat parameters: - name: Idempotency-Key in: header required: true schema: type: string description: >- 상태를 변경하는 POST 요청에 필요한 멱등성 키입니다. 24시간 동안 안전하게 재시도할 때 사용합니다. 값은 비어 있으면 안 됩니다. 최대 255자까지 허용합니다. minLength: 1 maxLength: 255 title: Idempotency-Key description: >- 상태를 변경하는 POST 요청에 필요한 멱등성 키입니다. 24시간 동안 안전하게 재시도할 때 사용합니다. 값은 비어 있으면 안 됩니다. 최대 255자까지 허용합니다. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateChatRequest' examples: current_agent: summary: current 에이전트로 채팅 생성 value: agent: agent_id: 7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a agent_version: current dynamic_variables: customer_name: 홍길동 metadata: crm_session_id: session_a1b2c3 external_id: customer_123 description: 채팅을 처리할 에이전트와 초기 설정입니다. responses: '201': description: 성공 응답 content: application/json: schema: $ref: '#/components/schemas/ChatResponse' '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: AGENT_NOT_FOUND message: 에이전트를 찾을 수 없습니다. details: agent_id: 7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a '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: {} security: - BearerAuth: [] components: schemas: CreateChatRequest: properties: agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' metadata: additionalProperties: true type: object title: Metadata description: 저장용 메타데이터입니다. 에이전트 처리에는 사용하지 않습니다. dynamic_variables: additionalProperties: true type: object title: Dynamic Variables description: 에이전트 프롬프트에 주입할 동적 변수입니다. external_id: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: External Id description: 고객사 서비스에서 사용하는 고객 식별자입니다. 지정하면 해당 식별자의 고객을 찾거나 생성해 채팅에 연결합니다. opening_message: anyOf: - type: string minLength: 1 - type: 'null' title: Opening Message description: >- 이 채팅의 첫 안내 메시지입니다. 지정하면 에이전트의 첫 메시지 설정보다 우선합니다. 에이전트는 첫 사용자 입력부터 실행합니다. type: object required: - agent title: CreateChatRequest ChatResponse: properties: provider_responder: anyOf: - type: string enum: - ai - external - unknown - type: 'null' title: Provider Responder description: 외부 채널 응대권의 조회 시점 상태입니다. 채널 원장에서 계산하며 별도로 저장하지 않습니다. id: type: string format: uuid title: Id description: 채팅 ID입니다. customer_id: anyOf: - type: string format: uuid - type: 'null' title: Customer Id description: 연결된 고객의 UUID입니다. 고객 식별자를 생략해도 익명 고객을 생성합니다. 고객 연결이 없으면 null일 수 있습니다. agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' channel: type: string pattern: ^[a-z][a-z0-9_]{0,31}$ title: Channel description: 채팅 채널입니다. 현재 api, widget, sms, kakao를 지원하며 등록된 채널 이름을 그대로 반환합니다. status: $ref: '#/components/schemas/ChatStatusEnum' description: 채팅 상태입니다. responder: $ref: '#/components/schemas/ChatResponderResponse' description: 현재 응답 주체입니다. AI, 상담사, 외부 채널 가운데 어느 쪽이 응답 중인지 확인합니다. metadata: additionalProperties: true type: object title: Metadata description: 생성 시 전달한 저장용 메타데이터입니다. dynamic_variables: additionalProperties: true type: object title: Dynamic Variables description: 생성 시 전달한 동적 변수입니다. start_at: type: integer title: Start At description: 채팅 시작 시각입니다. 밀리초 단위 Unix 타임스탬프입니다. end_at: anyOf: - type: integer - type: 'null' title: End At description: 채팅 종료 시각입니다. 밀리초 단위 Unix 타임스탬프이며 진행 중에는 null입니다. chat_analysis: anyOf: - $ref: '#/components/schemas/ChatAnalysisResponse' - type: 'null' description: 대화 종료 후 분석 결과입니다. 분석 완료 전에는 null 입니다. chat_cost: anyOf: - $ref: '#/components/schemas/ChatCostResponse' - type: 'null' description: 확정된 Chat AI 사용료입니다. active 상태이거나 전체 비용을 확정할 수 없으면 null입니다. transcript: items: oneOf: - $ref: '#/components/schemas/ChatTranscriptMessageResponse' - $ref: '#/components/schemas/ChatToolCallInvocationResponse' - $ref: '#/components/schemas/ChatToolCallResultResponse' discriminator: propertyName: role mapping: agent: $ref: '#/components/schemas/ChatTranscriptMessageResponse' tool_call_invocation: $ref: '#/components/schemas/ChatToolCallInvocationResponse' tool_call_result: $ref: '#/components/schemas/ChatToolCallResultResponse' user: $ref: '#/components/schemas/ChatTranscriptMessageResponse' type: array title: Transcript description: >- 채팅 대화록입니다. user/agent 메시지와 tool_call_invocation/tool_call_result 항목을 순서대로 포함합니다. type: object required: - id - customer_id - agent - channel - status - responder - metadata - dynamic_variables - start_at - end_at - chat_analysis - chat_cost - transcript title: ChatResponse 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입니다. AgentMapping: additionalProperties: false description: >- `agent_id`와 `agent_version` 매핑입니다. 요청·응답 모두에서 에이전트 매핑이 필요한 경우 이 타입을 사용합니다. version 지정이 필요 없는 엔드포인트는 flat `agent_id: UUID`를 직접 받고 `AgentMapping`을 사용하지 않습니다. properties: agent_id: description: 에이전트 UUID입니다. format: uuid title: Agent Id type: string agent_version: default: current description: >- 에이전트 버전입니다. 허용값은 "current", "production", "v{n}"(n≥1)입니다. 보내지 않으면 "current"로 처리합니다. null 전송은 거부합니다. title: Agent Version type: string pattern: ^(current|production|v[1-9][0-9]*)$ examples: - current - production - v1 required: - agent_id title: AgentMapping type: object ChatStatusEnum: type: string enum: - active - ended title: ChatStatusEnum ChatResponderResponse: properties: type: type: string enum: - ai - operator - external title: Type description: 현재 Chat 응답 주체입니다. external은 외부 채널에서 관리합니다. operator: anyOf: - $ref: '#/components/schemas/ChatResponderOperatorResponse' - type: 'null' description: 상담사 응답 중일 때의 공개 상담사 식별 정보입니다. since: type: integer title: Since description: 현재 응답 주체로 전환된 시각 (unix ms)입니다. type: object required: - type - operator - since title: ChatResponderResponse ChatAnalysisResponse: properties: summary: anyOf: - type: string - type: 'null' title: Summary description: 대화 내용의 자동 생성 요약입니다. user_sentiment: anyOf: - $ref: '#/components/schemas/UserSentimentDto' - type: 'null' description: 사용자의 감정 분석 결과입니다. 분석 완료 전에는 null입니다. custom_analysis_data: items: additionalProperties: true type: object type: array title: Custom Analysis Data description: 대화에서 수집된 사용자 정의 분석 데이터입니다. type: object required: - summary - user_sentiment - custom_analysis_data title: ChatAnalysisResponse description: 채팅 종료 후 생성된 분석 결과입니다. ChatCostResponse: properties: total_cost: type: string title: Total Cost description: 채팅 AI 사용료 합계(KRW 원 단위, Decimal 문자열)입니다. type: object required: - total_cost title: ChatCostResponse description: 확정된 채팅 AI 사용료입니다. ChatTranscriptMessageResponse: properties: id: type: integer title: Id description: 채팅 메시지 ID입니다. role: type: string enum: - user - agent title: Role description: 메시지 발화자 역할입니다. author: type: string enum: - customer - ai - operator - system title: Author description: 메시지를 실제로 작성한 주체입니다. content: anyOf: - type: string - type: 'null' title: Content description: 메시지 본문입니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. unix milliseconds 형식입니다. attachments: anyOf: - items: $ref: '#/components/schemas/ChatMessageAttachment' type: array - type: 'null' title: Attachments description: 메시지에 첨부된 이미지의 파일 키와 MIME 타입입니다. client_idempotency_key: anyOf: - type: string - type: 'null' title: Client Idempotency Key description: >- 사용자 메시지를 보낼 때 지정한 중복 전송 방지 키입니다. API·위젯 사용자 메시지에 포함되며, 응답을 받지 못한 요청이 저장됐는지 확인할 수 있습니다. type: object required: - id - role - author - content - created_at - attachments title: ChatTranscriptMessageResponse 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: 도구 호출 결과 텍스트입니다. 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`를 포함합니다. ChatResponderOperatorResponse: properties: member_id: anyOf: - type: string format: uuid - type: 'null' title: Member Id description: 현재 응답 중인 상담사의 워크스페이스 멤버 ID입니다. type: object required: - member_id title: ChatResponderOperatorResponse UserSentimentDto: type: string enum: - positive - negative - neutral - unknown title: UserSentimentDto description: 사용자 감정 enum입니다. 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 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Organization API key description: '워크스페이스 API 키를 `Authorization: Bearer ` 형식으로 보냅니다.' ````