> ## 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와 상담사가 함께 응대하기

> 메신저 문의에 AI 에이전트가 먼저 답하고, 필요할 때 상담사가 이어받았다가 AI 응대로 복귀하는 상담 체계를 만들 수 있어요.

상담사는 AI가 응대하던 같은 대화를 이어받고, 처리가 끝나면 AI 응대로 복귀하거나 채팅을 끝내요.

## 만들게 될 것

* **메신저 채널**: 카카오, 네이버톡톡, 인스타그램 같은 [채널](https://docs.tryvox.co/docs/operate/deploy/integrations/overview.md)이나 직접 만든 [채팅 API](https://docs.tryvox.co/docs/operate/deploy/chat-api.md) 화면이에요.
* **vox.ai 에이전트**: 고객에게 먼저 답하고, 상담사가 필요하다고 판단하면 `transfer` 도구를 호출해요.
* **고객사 서버**: `transfer` 요청을 받아 상담사에게 넘기고, 채팅 웹훅으로 새 메시지를 받아요. vox.ai API를 호출해요.
* **상담 화면**: 상담사가 대기 중인 채팅을 확인하고 이어받아 답장하는 고객사 화면이에요.

## 대시보드에서 먼저 해 보기

코드 없이 이어받기부터 해 보세요. 워크스페이스 멤버라면 누구나 할 수 있고, 모든 채널에서 같아요. 다른 상담사가 이미 맡은 채팅은 이어받을 수 없어요.

**1. 진행 중인 채팅 열기**

**기록**의 **채팅** 탭에서 **상태**를 **진행 중**으로 고르고 채팅을 누르세요.

**2. 이어받고 답장하기**

상세 아래 입력칸에서 **이어받기**를 누르세요. 그 뒤 고객 메시지에는 AI가 답하지 않아요. 답장을 쓰고 **보내기**를 누르면 고객 메신저로 전달돼요. 채팅 API로 만든 채팅은 대화록에만 저장되니, 고객 화면에서 대화록을 다시 불러와 보여 주세요.

**3. AI 응대로 복귀하거나 끝내기**

**AI 응대 복귀**를 누르면 다음 고객 메시지부터 AI가 답해요. 상담을 마치려면 **대화 종료**를 누르세요.

상담사가 많거나 상담 화면을 고객사 업무 도구 안에 두려면 아래처럼 직접 만드세요.

## 응답 담당이 바뀌는 방식

채팅마다 현재 응대를 맡는 응답 담당이 정해져 있어요. 값은 [채팅 조회](https://docs.tryvox.co/api-reference/v3/chats/채팅-조회.md) API의 `responder.type`이고, `agent`는 AI 에이전트, `operator`는 상담사예요.

| 바뀜 | 누가 일으키나 | 어떻게 |
| - | - | - |
| `agent` → `operator` | AI 에이전트 | `transfer` 도구를 호출하면 고객사 서버가 [상담사 이어받기](https://docs.tryvox.co/api-reference/v3/chats/상담사-이어받기.md)를 호출해요 |
| `agent` → `operator` | 상담사 | 상담 화면이나 대시보드에서 이어받아요 |
| `agent` → `operator` | 채널 | 채널톡 매니저가 채널톡에서 답하거나, 네이버톡톡 고객의 상담사 연결 요청으로 응대가 파트너센터로 넘어가요 |
| `operator` → `agent` | 상담사 | [AI 응대 복귀](https://docs.tryvox.co/api-reference/v3/chats/ai-응대-복귀.md)를 호출해요 |

응답 담당이 `operator`인 동안 고객 메시지는 저장만 되고 AI가 답하지 않아요. 상담사가 맡은 채팅은 대화가 오래 없어도 자동으로 끝나지 않아요. 카카오처럼 채널이 상담을 끝내는 경우는 [채널별로 다른 점](#채널별로-다른-점)을 보세요.

AI 에이전트가 상담사를 부르는 순서는 이래요.

```mermaid theme={null}
sequenceDiagram
  participant 고객
  participant vox as vox.ai
  participant 서버 as 고객사 서버
  participant 화면 as 상담 화면
  고객->>vox: 환불하고 싶어요
  vox->>서버: transfer 도구 호출 (chat_id, chat_turn_id, reason)
  서버->>vox: POST /takeover
  서버->>화면: 대기 채팅 알림
  서버->>vox: POST /outbound-messages (연결 안내)
  vox->>고객: 상담사에게 연결해 드릴게요
  서버-->>vox: 도구 응답
  고객->>vox: 언제 연결돼요?
  vox->>서버: chat_message_received (responder_type=operator)
  화면->>서버: 상담사 답장
  서버->>vox: POST /outbound-messages (origin=operator)
  vox->>고객: 상담사 답장
  화면->>서버: AI 응대 복귀
  서버->>vox: POST /release
```

이어받기가 AI 답변보다 먼저 끝나면 그 차례에 AI가 만든 답변과 도구 호출 기록은 저장되거나 전송되지 않아요. 그래서 고객에게 보일 연결 안내는 고객사 서버가 이어받은 직후 직접 보내야 해요.

## 직접 만들기

모든 요청은 고객사 서버에서 워크스페이스 [API 키](https://docs.tryvox.co/api-reference/v3/introduction.md#인증)로 보내요. 주소는 `https://client-api.tryvox.co/v3`예요.

### transfer 도구 만들기

[API 도구](https://docs.tryvox.co/docs/build/tools/api.md)를 하나 만들어 에이전트에 연결하세요. 헤더의 [`{{chat_id}}`, `{{chat_turn_id}}`](https://docs.tryvox.co/docs/build/variables/system-variables#채팅-변수)는 vox.ai가 현재 채팅과 처리 중인 고객 메시지 값으로 채워요. 아래 본문으로 [도구 생성](https://docs.tryvox.co/api-reference/v3/tools/도구-생성.md) API를 호출하거나, 대시보드 **구축 > 도구**에서 같은 값으로 만드세요.

```json theme={null}
{
  "name": "transfer",
  "description": "고객을 상담사에게 연결합니다. 고객이 사람을 원하거나, AI가 해결할 수 없는 요청일 때 호출합니다.",
  "input_schema": {
    "type": "object",
    "properties": {
      "reason": { "type": "string", "description": "고객의 용건과 연결 사유 한 문장" }
    },
    "required": ["reason"]
  },
  "api_configuration": {
    "url": "https://support.example.com/vox/transfer",
    "method": "POST",
    "headers": {
      "X-Chat-Id": "{{chat_id}}",
      "X-Chat-Turn-Id": "{{chat_turn_id}}"
    },
    "auth_type": "Bearer",
    "auth_credentials": "고객사 서버가 확인할 비밀 값",
    "timeout_seconds": 10
  },
  "response_mode": "wait"
}
```

`auth_credentials`에는 vox.ai API 키가 아니라 고객사 서버가 도구 요청을 확인할 별도의 비밀 값을 넣으세요.

### 프롬프트에 호출 조건 적기

에이전트 프롬프트에 `transfer`를 호출할 조건을 적으세요.

```text theme={null}
## 상담사 연결
아래 경우에는 transfer 도구를 호출하세요. reason에는 고객의 용건을 한 문장으로 적으세요.
- 고객이 상담사나 사람과 이야기하고 싶다고 하면 되묻지 말고 바로 호출하세요.
- 같은 문제를 두 번 안내했는데도 해결되지 않았을 때
- 환불, 결제 취소, 보상, 계정 소유 확인처럼 사람이 처리해야 하는 요청일 때
- 고객이 화가 났거나 불만을 강하게 표현할 때
도구 결과의 connected가 false면 결과의 message를 그대로 안내하세요.
```

도구와 프롬프트는 채널이 쓰는 에이전트 버전에 들어가야 동작해요. 채널이 **현재** 편집본을 쓰면 배포하지 않아도 돼요. 프로덕션이나 특정 버전을 쓰면 [배포](https://docs.tryvox.co/docs/build/versioning.md)한 뒤 그 버전을 프로덕션으로 지정하거나 채널에 연결하세요. 새 채팅부터 적용돼요.

### 도구 요청 받기

고객사 서버가 도구 요청을 받으면 이어받기, 대기 목록 등록, 연결 안내 순서로 처리한 뒤 응답하세요. 안내가 실패해도 대기 건은 남기고 실패를 대기 건에 표시하세요. 응답하기 전에 이어받아야 AI 답변과 연결 안내가 겹쳐 나가지 않아요. 같은 차례의 요청이 다시 와도 한 번만 처리되도록 `chat_turn_id`로 키를 만드세요.

```python theme={null}
import os
import httpx
from fastapi import FastAPI, Header, HTTPException, Request

app = FastAPI()
VOX = httpx.AsyncClient(
    base_url=os.environ["VOX_BASE_URL"],  # https://client-api.tryvox.co/v3
    headers={"Authorization": f"Bearer {os.environ['VOX_API_KEY']}"},
    timeout=8,
)

@app.post("/vox/transfer")
async def transfer(
    request: Request,
    authorization: str = Header(),
    x_chat_id: str = Header(),
    x_chat_turn_id: str = Header(),
):
    if authorization != f"Bearer {os.environ['TRANSFER_TOOL_SECRET']}":
        raise HTTPException(status_code=401)
    reason = (await request.json()).get("reason", "")

    if not is_open_now():  # 고객사 상담 시간 판단
        return {"connected": False, "message": "지금은 상담 시간이 아니에요. 평일 9시부터 18시 사이에 다시 문의해 주세요."}

    takeover = await VOX.post(
        f"/chats/{x_chat_id}/takeover",
        headers={"Idempotency-Key": f"transfer-{x_chat_turn_id}"},
    )
    if takeover.status_code != 200:
        return {"connected": False, "message": "지금은 상담사를 연결하지 못했어요. 잠시 뒤 다시 요청해 주세요."}

    await enqueue_waiting_chat(x_chat_id, reason, dedupe_key=x_chat_turn_id)  # 상담 화면 대기 목록
    channel = takeover.json()["channel"]
    try:
        notice = await VOX.post(f"/chats/{x_chat_id}/outbound-messages", json={
            "origin": "operator" if channel in ("navertalk", "wechat") else "system",
            "text": "상담사에게 연결해 드릴게요. 잠시만 기다려 주세요.",
            "client_idempotency_key": f"transfer-notice-{x_chat_turn_id}",
        })
        notice_ok = notice.status_code == 201
    except httpx.HTTPError:
        notice_ok = False
    if not notice_ok:
        await mark_notice_failed(x_chat_id, dedupe_key=x_chat_turn_id)  # 대기 건에 안내 실패 표시
    return {"connected": True}
```

`is_open_now()`, `enqueue_waiting_chat()`, `mark_notice_failed()`는 고객사 상담 시간과 상담 화면 저장소에 맞게 직접 구현하세요. 상담 시간이 아닐 때처럼 이어받지 않고 응답하면 AI가 도구 결과를 보고 고객에게 안내해요.

### 채팅 웹훅 받기

상담 화면은 [채팅 웹훅](https://docs.tryvox.co/docs/operate/monitor/webhooks/schema.md#채팅-이벤트)으로 새 메시지를 받아요. **설정 > 웹훅**의 **이벤트 구독**에서 **채팅 시작**, **메시지 수신**, **메시지 발신 결과**, **채팅 종료**를 켜세요. 채널이 쓰는 에이전트 버전에 **채팅 웹훅 URL**이 있으면 워크스페이스 웹훅 URL보다 우선해요. 상담 서버 주소인지 확인하세요.

* **[`chat_started`](https://docs.tryvox.co/docs/operate/monitor/webhooks/schema#chat_started)**: 새 채팅이에요. `chat.responder_type`이 `agent`면 AI 응대 중 목록에 올려 상담사가 먼저 이어받을 수 있게 하고, `operator`면 상담사 대기 목록에 올리세요.
* **[`chat_message_received`](https://docs.tryvox.co/docs/operate/monitor/webhooks/schema#chat_message_received)**: 고객 메시지예요. `chat.responder_type`이 `operator`면 상담사가 답할 메시지이니 대기 상태와 읽지 않음 표시를 갱신하세요.
* **[`chat_message_sent`](https://docs.tryvox.co/docs/operate/monitor/webhooks/schema#chat_message_sent)**: AI 답변, 상담사 답장, 안내의 발신 결과예요. `message.role`은 각각 `agent`, `operator`, `system`이에요. `status`가 `failed`면 `error.code`를 상담사에게 보여 주세요.
* **[`chat_ended`](https://docs.tryvox.co/docs/operate/monitor/webhooks/schema#chat_ended)**: 채팅이 끝났어요. 목록에서 닫으세요.

[`responder_type`](https://docs.tryvox.co/docs/operate/monitor/webhooks/schema#응답-담당-읽기)은 웹훅을 보내는 시점의 값이에요. 메시지를 누가 썼는지는 `message.role`로 확인하세요. 이어받기 전 대화는 [채팅 조회](https://docs.tryvox.co/api-reference/v3/chats/채팅-조회.md) API의 `transcript`로 불러오세요. 이어받기와 AI 응대 복귀에는 웹훅이 오지 않아요. 고객사 서버가 호출했을 때는 API 응답의 `responder`로 화면을 바로 갱신하세요.

### 상담사 답장 보내기

[메시지 직접 전송](https://docs.tryvox.co/api-reference/v3/chats/메시지-직접-전송.md) API에 `origin`을 `operator`로 넣어 보내세요. 이어받은 채팅에만 보낼 수 있어요. 답장마다 새 `client_idempotency_key`를 쓰세요.

```bash theme={null}
curl -X POST "https://client-api.tryvox.co/v3/chats/$CHAT_ID/outbound-messages" \
  -H "Authorization: Bearer $VOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "origin": "operator", "text": "환불 접수해 드렸어요.", "client_idempotency_key": "reply-001" }'
```

### AI 응대 복귀나 채팅 끝내기

고객 용건을 해결했으면 `POST /v3/chats/{chat_id}/release`로 [AI 응대 복귀](https://docs.tryvox.co/api-reference/v3/chats/ai-응대-복귀.md)를 호출하고, 더 할 말이 없으면 `POST /v3/chats/{chat_id}/end`로 채팅을 끝내세요. 용건이 남은 채로 복귀하면 AI가 같은 내용을 다시 물어요.

복귀에도 `Idempotency-Key` 헤더가 필요해요. 채널이 AI 응답을 허용하지 않으면 복귀가 `AGENT_RESPONSE_NOT_ALLOWED`로 거절돼요. 이때는 상담사가 계속 답하세요.

## 상담사가 먼저 이어받기

AI가 부르지 않아도 상담사는 AI가 응대 중인 채팅을 언제든 이어받을 수 있어요. 상담 화면에서 `Idempotency-Key` 헤더와 함께 `POST /v3/chats/{chat_id}/takeover`로 [상담사 이어받기](https://docs.tryvox.co/api-reference/v3/chats/상담사-이어받기.md)를 호출하세요. 대시보드에서 다른 상담사가 이미 맡은 채팅은 `409 CHAT_RESPONDER_CONFLICT`로 거절돼요. 진행 중인 채팅은 `GET /v3/chats?status=active`로 찾아요.

AI가 답을 만드는 중에 이어받으면 그 답은 고객에게 가지 않아요. 상담사가 맡았다고 알리려면 [채널별로 다른 점](#채널별로-다른-점)에 따라 안내를 보내세요.

## AI 응대 복귀 뒤 AI가 아는 것

복귀하면 AI는 새 맥락으로 시작해요. 상담사가 안내한 주문번호처럼 복귀 전에 오간 내용을 물으면 답하지 못해요.

* **AI가 이어서 쓰는 것**: 채팅의 [동적 변수](https://docs.tryvox.co/docs/build/variables/dynamic-variables.md), [고객 메모리](https://docs.tryvox.co/docs/build/customer-memory/overview.md)
* **AI가 읽지 못하는 것**: 복귀 전의 대화 전부. 그전 대화, 상담사 답장, 상담사가 맡은 동안 온 고객 메시지가 모두 포함돼요
* **AI가 답하는 때**: 복귀 뒤 새로 온 고객 메시지부터예요. 상담사가 맡은 동안 온 메시지에는 답하지 않아요

## 채널별로 다른 점

이어받기, 상담사 답장, AI 응대 복귀는 모든 채널에서 같은 API를 써요. [AI 응답 요청](https://docs.tryvox.co/api-reference/v3/chats/ai-응답-요청.md)만 채팅 API 채널 전용이에요. 다른 채널의 고객 메시지는 각 채널에서 들어와요.

| 채널 | 상담사 답장 | 답장 시간 제한과 주의 |
| - | - | - |
| 채팅 API, 위젯 | 글자, 이미지 3장 | - |
| 문자 | 글자, 이미지 3장 | - |
| 카카오 | 글자, 이미지 1장(글자와 함께, 1,000자 이하) | 카카오가 상담 세션을 끝내면 응답 담당과 상관없이 채팅이 끝나요. 연결하면 관리자센터의 1:1 채팅이 꺼져요 |
| 네이버톡톡 | 글자, 이미지 3장 | 파트너센터에서도 답할 수 있어요. [파트너센터에서 응대하기](https://docs.tryvox.co/docs/operate/deploy/integrations/navertalk/overview.md#파트너센터에서-응대하기) |
| 인스타그램 | 글자 | 고객의 마지막 DM 뒤 24시간 안에만 보낼 수 있어요 |
| 라인 | 글자 | 상담사 답장은 공식 계정의 월 메시지 수에 들어가요 |
| 위챗 | 글자 | 고객의 마지막 메시지 뒤 48시간 안에 5개까지 보낼 수 있어요 |
| 채널톡 | 글자 | 매니저가 채널톡에서 답하면 AI가 멈춰요. vox.ai에서 보낸 답장은 연결된 봇 이름으로 나가요 |

이어받은 뒤 보내는 연결 안내의 `origin`은 이어받기 응답의 `channel`이 `navertalk`나 `wechat`이면 `operator`, 그 밖에는 `system`이에요. 네이버톡톡과 위챗은 `origin`이 `system`인 안내에 처리 중인 고객 메시지를 지정해야 하기 때문이에요.

## 운영 전에 점검하기

* **아무도 이어받지 않을 때**: 대기 시간이 길어지면 상담 화면에서 알리고, 안내를 보내거나 채팅을 끝내세요.
* **상담사 인증**: 상담 화면과 그 화면이 부르는 고객사 서버 API에 직원 인증을 붙이세요.
* **두 상담사가 같은 채팅에 답할 때**: 같은 API 키로 호출하면 vox.ai는 모두 같은 응답 담당으로 봐요. 담당 상담사 배정과 잠금은 고객사 서버에서 하세요.
* **웹훅 순서와 중복**: 메시지는 `message.message_at`으로 정렬하고 `(event, message.id)`로 중복을 거르세요. 5초 안에 2xx를 돌려주고, 놓친 메시지는 채팅 조회로 채우세요. 규칙은 [전달 보장과 재시도](https://docs.tryvox.co/docs/operate/monitor/webhooks/schema.md#전달-보장과-재시도)에 있어요.
* **서명 검증**: 웹훅과 도구 요청이 vox.ai에서 왔는지 확인하세요. 웹훅은 [요청 검증하기](https://docs.tryvox.co/docs/operate/monitor/webhooks/organization.md#요청-검증하기)를 따르세요.
* **누가 답했는지 기록**: 이어받기와 답장 요청에는 상담사를 구분하는 값이 없고, 대화록에는 응답 담당이 바뀐 기록이 남지 않아요. 상담사, 이어받은 시각, 답장 응답의 `id`를 고객사 DB에 남기세요.
* **호출 한도**: v3 API는 워크스페이스마다 기본 초당 5회, 분당 120회예요. 대기 목록은 조회를 반복하지 말고 웹훅으로 채우세요.
* **비용**: 채팅 요금과 채널 요금은 [요금](https://docs.tryvox.co/docs/start/pricing.md#채팅-요금)에서 확인하세요.

## 관련 문서

* [채팅 API](https://docs.tryvox.co/docs/operate/deploy/chat-api.md): 직접 만든 채팅 화면에 에이전트 연결하기
* [웹훅 스키마](https://docs.tryvox.co/docs/operate/monitor/webhooks/schema.md#채팅-이벤트): 채팅 이벤트의 필드와 전달 규칙
* [API 도구](https://docs.tryvox.co/docs/build/tools/api.md): 에이전트가 고객사 서버를 호출하게 하기
* [시스템 변수](https://docs.tryvox.co/docs/build/variables/system-variables.md#채팅-변수): `chat_id`, `chat_turn_id`
* [채팅 기록](https://docs.tryvox.co/docs/operate/monitor/chats.md): 대시보드에서 채팅 찾아보기


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