> ## 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. # 진행 중 통화 맥락 전달 요청 > 진행 중인 통화에 텍스트 맥락을 전달합니다. 에이전트는 이후 응답에 이 맥락을 참고하며, 먼저 말할지는 `response`로 정합니다. 202 응답은 통화에 전달하도록 요청을 수락했다는 뜻이며, 결과는 같은 `control_id`를 담은 `call_context` 웹훅으로 나중에 알립니다. ## OpenAPI ````yaml /api-reference/v3/openapi.json post /calls/{call_id}/context 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: /calls/{call_id}/context: post: tags: - Calls summary: 진행 중 통화 맥락 전달 요청 description: >- 진행 중인 통화에 텍스트 맥락을 전달합니다. 에이전트는 이후 응답에 이 맥락을 참고하며, 먼저 말할지는 `response`로 정합니다. 202 응답은 통화에 전달하도록 요청을 수락했다는 뜻이며, 결과는 같은 `control_id`를 담은 `call_context` 웹훅으로 나중에 알립니다. operationId: injectCallContext parameters: - name: call_id in: path required: true schema: type: string format: uuid title: Call 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: >- 상태를 변경하는 POST 요청에 필요한 멱등성 키입니다. 24시간 동안 안전하게 재시도할 때 사용합니다. 값은 비어 있으면 안 됩니다. 최대 255자까지 허용합니다. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InjectCallContextRequest' examples: interrupt_agent: summary: 에이전트 말을 끊고 바로 안내 value: text: 고객이 방금 결제를 마쳤습니다. 주문번호는 A-1024입니다. response: interrupt_agent expires_in_seconds: 30 when_idle: summary: 통화가 조용해지면 한 번 안내 value: text: 본인 확인이 끝났습니다. 이제 주소 변경을 진행할 수 있습니다. response: when_idle remember_only: summary: 먼저 말하지 않고 기억만 value: text: 고객 등급은 VIP이고 최근 주문은 2026-11-10의 A-0981입니다. response: none description: >- 맥락 전달 요청 본문입니다. `expires_in_seconds`는 `response`가 `when_idle`이나 `interrupt_agent`일 때만 보냅니다. responses: '202': description: 성공 응답 content: application/json: schema: $ref: '#/components/schemas/InjectCallContextResponse' '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 invalidContextRequest: summary: response가 none인데 expires_in_seconds를 보냈습니다. value: error: code: INVALID_CONTEXT_REQUEST message: >- expires_in_seconds는 response가 when_idle 또는 interrupt_agent일 때만 지정할 수 있습니다. details: field: expires_in_seconds response: none '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: organizationAccessDenied: summary: 요청한 워크스페이스에 접근할 권한이 없습니다. value: error: code: ORGANIZATION_ACCESS_DENIED message: 해당 조직에 대한 접근 권한이 없습니다. details: {} '404': description: 리소스를 찾을 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: 통화를 찾을 수 없습니다. value: error: code: CALL_NOT_FOUND message: 통화를 찾을 수 없습니다. details: call_id: 33333333-3333-4333-8333-333333333333 '409': description: 충돌이 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: callNotActive: summary: 진행 중인 통화가 아닙니다. value: error: code: CALL_NOT_ACTIVE message: 진행 중인 통화에만 맥락을 넣을 수 있습니다. details: call_id: 33333333-3333-4333-8333-333333333333 contextNotSupported: summary: 맥락을 전달할 수 없는 통화 유형입니다. value: error: code: CONTEXT_NOT_SUPPORTED message: 이 통화 유형에서는 맥락 전달을 지원하지 않습니다. details: call_id: 33333333-3333-4333-8333-333333333333 contextTargetAmbiguous: summary: 통화에 에이전트가 둘 이상 있습니다. value: error: code: CONTEXT_TARGET_AMBIGUOUS message: 통화방에 Agent 참가자가 둘 이상이라 맥락을 전달할 수 없습니다. details: call_id: 33333333-3333-4333-8333-333333333333 idempotencyKeyConflict: summary: 같은 Idempotency-Key를 다른 요청에 다시 사용했습니다. value: error: code: IDEMPOTENCY_KEY_CONFLICT message: 동일한 Idempotency-Key가 다른 요청 또는 실행 주체에 사용되었습니다. details: idempotency_key: context-request-001 idempotencyKeyInProgress: summary: 같은 Idempotency-Key의 요청을 아직 처리하는 중입니다. value: error: code: IDEMPOTENCY_KEY_IN_PROGRESS message: 이 Idempotency-Key는 현재 처리 중입니다. 잠시 후 다시 시도해 주세요. details: idempotency_key: context-request-001 '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 contextLimitExceeded: summary: 통화당 한도(초당 2회, 분당 10회, 말하기를 기다리는 요청 8건, 텍스트 64KiB)를 넘었습니다. value: error: code: CONTEXT_LIMIT_EXCEEDED message: 통화당 맥락 요청 한도를 초과했습니다. details: limit: requests_per_second max: 2 '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: contextCommandUnavailableRetryable: summary: 맥락을 전달하지 못했습니다. 같은 키로 다시 보낼 수 있습니다. value: error: code: CONTEXT_COMMAND_UNAVAILABLE message: 통화 맥락 명령을 전달할 수 없습니다. details: retryable: true contextCommandUnavailableNonRetryable: summary: 전달 결과를 알 수 없습니다. 다시 보낼 때는 같은 키만 사용합니다. value: error: code: CONTEXT_COMMAND_UNAVAILABLE message: 통화 맥락 명령을 전달할 수 없습니다. details: retryable: false security: - BearerAuth: [] components: schemas: InjectCallContextRequest: properties: text: type: string title: Text description: >- 통화에 전달할 맥락입니다. 공백만 있거나 NUL 문자가 있거나 요청 정보를 더해 UTF-8 16KiB를 넘으면 400 `INVALID_CONTEXT_REQUEST`입니다. 에이전트는 고객의 말이나 지시가 아닌 업무 시스템 데이터로 이후 응답에 참고합니다. response: type: string enum: - none - when_idle - interrupt_agent title: Response description: >- 에이전트가 먼저 말할지 정합니다. 기본값 `none`은 기억만 하고, `when_idle`은 통화가 조용해지면 한 번 말하고, `interrupt_agent`는 에이전트의 말을 끊고 바로 답합니다. 고객이 말하는 중이면 둘 다 말이 끝난 뒤 답에 합칩니다. default: none expires_in_seconds: anyOf: - type: integer - type: 'null' maximum: 180 minimum: 1 title: Expires In Seconds description: >- 말하기 시작할 때까지의 기한(초)입니다. `when_idle`·`interrupt_agent`에서만 1~180, 기본 90초이며 `none`에 보내거나 범위를 벗어나면 400 `INVALID_CONTEXT_REQUEST`입니다. 지나면 말하지 않고 맥락만 남습니다. additionalProperties: false type: object required: - text title: InjectCallContextRequest description: 진행 중인 통화에 맥락을 전달하는 요청입니다. InjectCallContextResponse: properties: call_id: type: string format: uuid title: Call Id description: 맥락을 보낸 통화 UUID입니다. control_id: type: string title: Control Id description: >- 요청 ID입니다. 같은 `Idempotency-Key`면 같은 값이며 `call_context` 웹훅의 `control_id`와 같습니다. status: type: string const: accepted title: Status description: >- 항상 `accepted`입니다. 통화에 전달하도록 요청을 수락했다는 뜻이며, 반영·발화 결과는 텍스트 없이 `call_context` 웹훅으로 알립니다. type: object required: - call_id - control_id - status title: InjectCallContextResponse description: 맥락 전달 요청을 수락했을 때의 202 응답입니다. 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입니다. 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`를 포함합니다. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Organization API key description: '워크스페이스 API 키를 `Authorization: Bearer ` 형식으로 보냅니다.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.