> ## 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 채팅

> 직접 만든 웹·앱 채팅 화면에 에이전트를 연결해 고객사 서버에서 메시지를 주고받을 수 있어요.

API 채팅은 직접 만든 웹·앱 채팅 화면에 에이전트를 연결해요. 고객사 서버가 사용자 메시지를 보내고 AI 응답을 받아 화면에 보여 줘요.

```mermaid theme={null}
sequenceDiagram
  participant 사용자
  participant 화면 as 고객사 채팅 화면
  participant 서버 as 고객사 서버
  participant 에이전트 as vox.ai 에이전트
  화면->>서버: 새 상담 시작
  서버->>에이전트: 채팅 생성
  에이전트-->>서버: 채팅 ID와 첫 대화 내역
  서버-->>화면: 첫 대화 표시
  loop 상담 중
    사용자->>화면: 메시지 입력
    화면->>서버: 사용자 메시지
    서버->>에이전트: 메시지 전송
    에이전트-->>서버: AI 응답과 채팅 상태
    서버-->>화면: 응답 표시
  end
  화면->>서버: 상담 종료
  서버->>에이전트: 채팅 종료
  에이전트-->>서버: 종료 완료
```

API 채팅에는 전화번호나 위젯 설치가 필요 없어요. vox.ai가 제공하는 채팅 화면을 쓰려면 [위젯](/docs/operate/deploy/widget/overview)을 쓰세요.

## 준비물

* **에이전트**: [프롬프트 에이전트](/docs/build/single-prompt/overview)나 [플로우 에이전트](/docs/build/flow/overview)를 만들고, 에이전트 ID와 쓸 [버전](/docs/build/versioning)을 확인하세요.
* **API 키**: [API 인증](/api-reference/v3/introduction#인증)에 쓸 워크스페이스 API 키를 발급하세요. 키는 고객사 서버에만 두고 브라우저 코드나 모바일 앱에 넣지 마세요. 아래 요청은 모두 서버에서 실행하는 예제예요.
* **요금제**: 워크스페이스의 [요금제](/docs/start/pricing)가 활성 상태인지 확인하세요.

## 채팅 연결하기

다음 예제에서 `$VOX_API_KEY`는 발급한 API 키예요. 에이전트 UUID는 실제 값으로 바꾸고, `$CHAT_ID`에는 채팅을 만든 응답의 `id`를 넣으세요.

<Steps>
  <Step title="채팅 만들기">
    `POST /v3/chats`로 채팅을 만드세요. `agent.agent_id`는 필수예요. `agent_version`을 생략하면 `current`를 써요.

    ```bash theme={null}
    curl -X POST https://client-api.tryvox.co/v3/chats \
      -H "Authorization: Bearer $VOX_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: chat-create-001" \
      -d '{
        "agent": {
          "agent_id": "11111111-1111-4111-8111-111111111111",
          "agent_version": "current"
        },
        "external_id": "customer-123",
        "opening_message": "안녕하세요. 무엇을 도와드릴까요?"
      }'
    ```

    성공하면 `201`과 채팅 정보를 돌려줘요. 응답의 `id`가 채팅 ID이고, `transcript`에 첫 대화 내역이 담겨요. 응답 예시는 아래 [응답 읽기](#응답-읽기)에 있어요.

    `external_id`로 고객사 서비스의 고객을 연결하세요. 생략하면 익명 고객을 만들어요. 고객에 맞춘 응대에는 [동적 변수](/docs/build/variables/dynamic-variables)를 쓰세요. `metadata`는 저장용이라 프롬프트에 들어가지 않아요.

    `opening_message`를 지정하면 첫 안내로 쓰고, 에이전트는 첫 사용자 입력부터 실행해요. 생략하면 [에이전트의 첫 메시지 설정](/docs/build/conversation/first-message)을 따르고, 설정에 따라 첫 대화 내역이 비어 있을 수 있어요.
  </Step>

  <Step title="사용자 메시지 보내기">
    `POST /v3/chats/{chat_id}/messages`로 보내세요. 같은 채팅의 응답을 받은 뒤 다음 메시지를 보내세요.

    ```bash theme={null}
    curl -X POST "https://client-api.tryvox.co/v3/chats/$CHAT_ID/messages" \
      -H "Authorization: Bearer $VOX_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "text": "배송 상태를 알려주세요.",
        "client_idempotency_key": "message-001"
      }'
    ```

    AI 응답을 기다린 뒤 `200`과 결과를 받아요. 응답 예시는 아래 [응답 읽기](#응답-읽기)에 있어요.

    `output`은 이번 응답에서 생긴 항목의 배열이에요. 메시지는 `role: "agent"`로 구분하고, 도구 호출과 결과도 들어 있을 수 있어요. `chat_status: "ended"`이면 입력을 끝내세요. 종료 응답에는 텍스트 메시지가 없을 수도 있어요.

    상담사가 응답 중이면 `202`를 받아요. 사용자 메시지는 저장되지만 AI는 답하지 않고, 응답에는 `output` 대신 `responder: "operator"`가 있어요. 이후 대화는 상세 조회로 확인하세요.
  </Step>

  <Step title="대화 내역 불러오기">
    `GET /v3/chats/{chat_id}`로 조회하세요. 화면을 다시 열 때 저장된 대화를 복원할 수 있어요.

    ```bash theme={null}
    curl "https://client-api.tryvox.co/v3/chats/$CHAT_ID" \
      -H "Authorization: Bearer $VOX_API_KEY"
    ```

    응답의 `transcript`는 전체 대화록이에요. 반복 조회할 때는 기존 목록을 응답으로 바꾸세요. 배열 전체를 이어 붙이면 메시지가 중복돼요.

    `role`은 메시지와 도구 항목을 구분해요. 메시지의 `author`는 실제 작성자이고, 값은 `customer`, `ai`, `operator`, `system`이에요. `chat_analysis`와 `chat_cost`도 조회할 수 있고, 아직 결과가 확정되지 않았으면 `null`이에요. 시각 필드는 밀리초 단위 Unix 타임스탬프예요.
  </Step>

  <Step title="채팅 끝내기">
    `POST /v3/chats/{chat_id}/end`로 끝내세요.

    ```bash theme={null}
    curl -X POST "https://client-api.tryvox.co/v3/chats/$CHAT_ID/end" \
      -H "Authorization: Bearer $VOX_API_KEY"
    ```

    성공하면 본문 없이 `204`를 돌려줘요. 이미 끝난 채팅에도 같은 응답을 돌려줘요. 끝난 뒤의 새 상담은 새 채팅으로 시작하세요.
  </Step>
</Steps>

## 응답 읽기

채팅을 만들면 `201`과 채팅 정보를 받아요. 아래는 응답에서 필요한 필드만 뽑은 예제예요.

```json theme={null}
{
  "id": "22222222-2222-4222-8222-222222222222",
  "channel": "api",
  "status": "active",
  "transcript": [
    {
      "id": 101,
      "role": "agent",
      "author": "ai",
      "content": "안녕하세요. 무엇을 도와드릴까요?",
      "created_at": 1789088400000,
      "attachments": null,
      "client_idempotency_key": null
    }
  ]
}
```

메시지를 보내면 AI 응답을 기다린 뒤 `200`과 이번 응답에서 생긴 항목을 받아요.

```json theme={null}
{
  "chat_id": "22222222-2222-4222-8222-222222222222",
  "chat_status": "active",
  "input_message_id": 102,
  "output": [
    {
      "id": 103,
      "role": "agent",
      "author": "ai",
      "content": "주문번호를 알려주시겠어요?",
      "created_at": 1789088405000,
      "attachments": null,
      "client_idempotency_key": null
    }
  ]
}
```

## 채팅 목록 조회하기

`GET /v3/chats`는 워크스페이스의 채팅 목록을 돌려줘요. 에이전트, 고객, 채널, 상태, 시작 시각으로 찾을 수 있어요. API로 만든 채팅만 보려면 `channel=api`를 지정하세요.

```bash theme={null}
curl 'https://client-api.tryvox.co/v3/chats?channel=api&status=active&limit=20' \
  -H "Authorization: Bearer $VOX_API_KEY"
```

목록 응답에는 `items`, `next_cursor`, `total_count`가 있어요. 다음 페이지는 `next_cursor`를 `cursor`로 넘기세요. 목록에는 `transcript`가 없으니 대화 내용은 상세 조회로 확인하세요.

| 채널          | 채팅을 만들고 메시지를 넣는 곳 | 목록·상세 조회    |
| ----------- | ----------------- | ----------- |
| `api`       | 이 페이지의 Chat API   | 공통 Chat API |
| `widget`    | 웹사이트에 설치한 위젯      | 공통 Chat API |
| `sms`       | 문자 채널             | 공통 Chat API |
| `kakao`     | 카카오 채널            | 공통 Chat API |
| `navertalk` | 네이버톡톡 연동          | 공통 Chat API |

채팅 만들기(`POST /chats`)와 메시지 보내기(`POST /chats/{chat_id}/messages`)는 API 채팅 전용이에요. 다른 채널의 고객 입력은 각 채널에서 받아요.

## 이미지 보내기

메시지에 이미지를 3장까지 넣을 수 있어요. `text`와 `images` 가운데 하나 이상이 있어야 하고, 이미지만 보내도 돼요.

| `images[].type` | 함께 보내는 필드                         |
| --------------- | --------------------------------- |
| `file_key`      | 업로드한 이미지의 `file_key`              |
| `base64`        | 이미지 데이터 `data`, 선택 항목 `mime_type` |
| `url`           | 이미지의 HTTPS `url`                  |

이미지 URL은 서버에서 접근할 수 있어야 해요. 이미지는 데이터 형식과 크기 검증을 거치고, JSON 요청 본문 전체는 10MiB까지예요.

```json theme={null}
{
  "text": "이 사진의 상품을 확인해주세요.",
  "images": [
    { "type": "file_key", "file_key": "file_abc123" }
  ],
  "client_idempotency_key": "message-002"
}
```

`file_key`는 [API 참조](/api-reference/v3/introduction)의 **파일** 그룹에 있는 파일 업로드(`POST /files`)에서 받은 값으로 바꾸세요.

## 중복 요청 막기

채팅 만들기와 메시지 보내기는 서로 다른 키를 써요.

* **채팅 만들기**: 헤더의 `Idempotency-Key`가 필수예요. 다시 보낼 때는 같은 요청 본문과 키로 보내세요.
* **메시지 보내기**: 본문의 `client_idempotency_key`가 필수예요. 다시 보낼 때는 같은 채팅에서 같은 메시지와 키로 보내세요.

새 상담이나 새 메시지에는 새 키를 만드세요. 예제 키를 모든 요청에 다시 쓰지 마세요. 응답을 받지 못했더라도 키를 바꾸지 말고 다시 보내세요. 저장됐는지는 상세 조회로 확인할 수도 있어요.

## 연결 확인

* 채팅을 만들고 메시지를 보낸 뒤 `chat_status`가 `active`인 `200` 응답의 `output`에 에이전트 메시지가 있는지 확인하세요. `202`나 종료된 채팅이면 상세 조회로 대화를 확인하세요.
* 대시보드 **기록**의 **채팅** 탭에서 **채널**을 **웹/API**로 골라 방금 만든 채팅과 대화 내용이 보이는지 확인하세요.

## 문제가 생겼을 때

<AccordionGroup>
  <Accordion title="메시지를 보내면 CHAT_BUSY 오류가 나요">
    앞 메시지의 응답을 받은 뒤 다시 보내세요. 같은 채팅의 이전 메시지를 아직 처리하고 있다는 뜻이에요.
  </Accordion>

  <Accordion title="CHAT_ENDED나 CHAT_CHANNEL_OPERATION_UNSUPPORTED 오류가 나요">
    `CHAT_ENDED`가 나면 새 상담은 채팅을 새로 만들어 시작하세요. 이미 끝난 채팅이라는 뜻이에요. `CHAT_CHANNEL_OPERATION_UNSUPPORTED`가 나면 그 채팅의 채널이 `api`인지 확인하세요.
  </Accordion>

  <Accordion title="CHAT_NOT_FOUND 오류가 나요">
    채팅 ID와, API 키가 속한 워크스페이스를 확인하세요.
  </Accordion>

  <Accordion title="429나 RATE_LIMIT_EXCEEDED 오류가 나요">
    요청 빈도를 줄이고, `429` 응답에 `Retry-After`가 있으면 그 시간만큼 기다린 뒤 다시 보내세요. 워크스페이스 API 키의 기본 한도는 초당 5회, 분당 120회이고 상세 조회도 같은 한도를 써요. 모든 채팅을 짧은 간격으로 반복 조회하지 마세요.
  </Accordion>
</AccordionGroup>

## 관련 문서

* [API 참조 소개](/api-reference/v3/introduction): 채팅 그룹에서 요청·응답 전체 필드와 오류 형식 보기
* [위젯 개요](/docs/operate/deploy/widget/overview): vox.ai가 제공하는 채팅 화면을 웹사이트에 설치하기
* [채팅 기록](/docs/operate/monitor/chats): 에이전트가 나눈 채팅을 찾아 대화 내용과 분석 보기
* [동적 변수](/docs/build/variables/dynamic-variables): 대화마다 고객 정보를 에이전트에 넘기기