> ## 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로 텍스트 맥락을 넣어요. 에이전트는 통화가 끝날 때까지 이 맥락을 반영하고, 응답 방식에 따라 먼저 말하기도 해요.

## 언제 사용하나요

* **통화 중에 외부 처리가 끝났을 때**: 결제나 본인 확인 결과로 바로 안내하게 해요.
* **CRM 정보를 알려 줄 때**: 고객 등급이나 최근 주문을 이후 답변에 쓰게 해요.
* **잘못된 안내를 바로잡을 때**: `interrupt_agent`로 말을 끊고 고친 내용으로 답하게 해요.

## 응답 방식 고르기

`response`로 에이전트가 맥락을 받은 뒤 먼저 말할지 정해요.

| `response` | 고객이 듣는 것 | 어울리는 정보 |
| - | - | - |
| `none`(기본) | 따로 말하지 않아요. 고객의 다음 말에 답할 때부터 맥락을 반영해요 | 참고만 하면 되는 정보 |
| `when_idle` | 통화가 조용해지면 맥락에 대해 한 번 먼저 말해요. 진행 중인 말은 끊지 않아요 | 지금 알리면 좋지만 급하지 않은 결과 |
| `interrupt_agent` | 에이전트가 말하는 중이면 그 말이 끊기고 바로 맥락에 대한 답이 나와요. 고객이 말하는 중이면 그 말이 끝난 뒤 답에 맥락을 합쳐요 | 지금 하는 안내를 멈추고 바로잡을 정보 |

`when_idle`과 `interrupt_agent`는 `expires_in_seconds` 안에 말을 시작하지 못하면 말하지 않아요. 이때도 맥락은 계속 반영돼요.

## API로 맥락 넣기

```bash cURL theme={null}
curl --request POST \
  --url https://client-api.tryvox.co/v3/calls/{call_id}/context \
  --header "Authorization: Bearer $VOX_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: context-request-001' \
  --data '{
    "text": "고객이 방금 결제를 마쳤다. 주문번호는 A-1024다.",
    "response": "interrupt_agent",
    "expires_in_seconds": 30
  }'
```

| 필드 | 값을 고르는 기준 |
| - | - |
| `text` | 필수예요. 에이전트가 알아야 할 사실을 적어요. 공백만 있거나, 서버가 요청 정보를 붙여 통화로 보내는 데이터가 UTF-8 16KiB를 넘으면 거절돼요 |
| `response` | `none`, `when_idle`, `interrupt_agent` 가운데 하나예요. 생략하면 `none`이에요 |
| `expires_in_seconds` | `when_idle`과 `interrupt_agent`에서만 1\~180초로 정해요. 생략하면 90초예요. `none`에 보내면 거절돼요 |

`Idempotency-Key` 헤더는 필수예요. 같은 키와 본문으로 다시 보내면 24시간 동안 처음 결과를 돌려주고 맥락을 다시 넣지 않아요. 같은 키에 다른 본문을 보내면 `409 IDEMPOTENCY_KEY_CONFLICT`가 와요.

HTTP `202`는 통화에 전달했다는 뜻까지예요. 응답의 `control_id`를 저장하고 결과는 [`call_context` 웹훅](#결과-확인하기)으로 확인하세요.

주요 거절 코드예요.

* `409 CALL_NOT_ACTIVE`: 진행 중(`ongoing`) 통화가 아니에요.
* `409 CONTEXT_NOT_SUPPORTED`: 음성 통화가 아니에요.
* `409 CONTEXT_TARGET_AMBIGUOUS`: 통화에 에이전트가 둘 이상이에요.
* `400 INVALID_CONTEXT_REQUEST`: 본문이 필드 규칙에 맞지 않아요.
* `429 CONTEXT_LIMIT_EXCEEDED`: 통화당 한도(초당 2회, 분당 10회, 말하기 대기 8건, 누적 64KiB)를 넘었어요.
* `503 CONTEXT_COMMAND_UNAVAILABLE`: 전달하지 못했어요. `details.retryable`이 `true`면 같은 키로 다시 보내세요. `false`면 이미 전달됐을 수 있어 새 키로 보내면 두 번 들어갈 수 있어요.

전체 필드와 응답 예시는 [진행 중 통화에 맥락 주입 API](https://docs.tryvox.co/api-reference/v3/calls/진행-중-통화에-맥락-주입.md)에 있어요.

[CLI](https://docs.tryvox.co/docs/ai/cli-reference.md#통화)에서는 `vox call context <call-id> --text "..." --response interrupt_agent`로 보내요. [MCP](https://docs.tryvox.co/docs/ai/mcp-reference.md#통화-조회와-발신)에서는 `inject_call_context` 도구로 같은 요청을 보내요.

## 통화에서 일어나는 일

* **맥락은 업무 시스템이 보낸 데이터로 전달돼요.** 에이전트는 고객의 말이나 지시로 다루지 않고, 스크립트에도 남지 않아요.
* **`when_idle`은 조용해진 뒤 잠시 기다려요.** 고객과 에이전트가 말을 멈추고 기본 1.5초가 지나면 말해요. 그사이 고객이 말하면 다시 기다려요.
* **`interrupt_agent`는 기다리지 않아요.** 에이전트가 말하는 중이면 새 답을 준비하는 동안 그 말을 이어 가다가, 새 답의 음성이 준비되는 순간 끊어요. 고객에게는 문장이 중간에 멈추고 맥락에 대한 답이 바로 이어져요.
* **끊지 않는 말도 있어요.** 끼어들 수 없게 보호한 [첫 메시지](https://docs.tryvox.co/docs/build/conversation/first-message.md)와 도구 실행 중인 말은 끝난 뒤 답해요.
* **말할 요청이 여러 개면 한 번에 말해요.** 도착 순서대로 모아 한 번에 답하고, `interrupt_agent` 요청이 있으면 그 시점을 따라요.
* **상담사 전환 중이나 통화 종료 중에는 반영하지 않아요.** 새 요청은 거절되고, 말하기를 기다리던 요청은 취소돼요.

## 결과 확인하기

요청마다 결과가 정해지면 통화 데이터 웹훅 URL로 `call_context` 이벤트가 한 번 와요. 따로 구독하지 않아도 와요. `control_id`로 요청과 짝을 맞추세요.

말했는지는 `reply`로 보세요. 끝까지 말하면 `completed`, 말하다 끊기면 `interrupted`, 고객 말에 대한 답에 합쳐지면 `merged`, 기한 안에 시작하지 못하면 `expired`예요. 값 전체는 [웹훅 스키마](https://docs.tryvox.co/docs/operate/monitor/webhooks/schema.md#call_context)에 있어요.

## 문제가 생겼을 때

> **에이전트가 맥락에 대해 먼저 말하지 않아요**
>
> response를 when\_idle이나 interrupt\_agent로 보내세요. none은 맥락을 기억만 하고 고객의 다음 말에 답할 때부터 반영해요.

> **interrupt\_agent인데 에이전트의 말이 끊기지 않아요**
>
> 첫 메시지 설정에서 첫 메시지 인터럽트 허용을 켜세요. 끼어들 수 없게 보호한 첫 인사나 도구를 실행하는 중인 말은 끊지 않고, 끝난 뒤 답해요.

> **reply가 expired로 와요**
>
> expires\_in\_seconds를 늘리세요. 고객이 길게 말하거나 끊을 수 없는 말이 이어지면 기한 안에 말을 시작하지 못해요.

> **call\_context 웹훅이 오지 않아요**
>
> 에이전트나 워크스페이스에 통화 데이터 웹훅 URL을 설정하세요. URL이 없으면 결과를 보내지 않아요.

## 관련 문서

* [웹훅 스키마](https://docs.tryvox.co/docs/operate/monitor/webhooks/schema.md#call_context): `call_context` 이벤트의 필드와 예시
* [통화 이벤트](https://docs.tryvox.co/docs/operate/monitor/webhooks/agent.md): 웹훅 수신 서버 만들기
* [통화 전환](https://docs.tryvox.co/docs/build/tools/builtin/transfer-call.md#api로-진행-중-통화-넘기기): API로 상담사에게 넘기기
* [첫 메시지](https://docs.tryvox.co/docs/build/conversation/first-message.md): 첫 인사에 끼어들 수 있게 하기


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