API 채팅

API 채팅은 직접 만든 웹·앱 채팅 화면에 에이전트를 연결해요. 고객사 서버가 사용자 메시지를 보내고 AI 응답을 받아 화면에 보여 줘요. API 채팅에는 전화번호나 위젯 설치가 필요 없어요. vox.ai가 제공하는 채팅 화면을 쓰려면 위젯을 쓰세요.

준비물

에이전트: 프롬프트 에이전트나 플로우 에이전트를 만들고, 에이전트 ID와 쓸 버전을 확인하세요.
API 키: API 인증에 쓸 워크스페이스 API 키를 발급하세요. 키는 고객사 서버에만 두고 브라우저 코드나 모바일 앱에 넣지 마세요. 아래 요청은 모두 서버에서 실행하는 예제예요.
요금제: 워크스페이스의 요금제가 활성 상태인지 확인하세요.

채팅 연결하기

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

채팅 만들기

POST /v3/chats로 채팅을 만드세요. agent.agent_id는 필수예요. agent_version을 생략하면 current를 써요.

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로 고객사 서비스의 고객을 연결하세요. 생략하면 익명 고객을 만들어요. 고객에 맞춘 응대에는 동적 변수를 쓰세요. metadata는 저장용이라 프롬프트에 들어가지 않아요.opening_message를 지정하면 첫 안내로 쓰고, 에이전트는 첫 사용자 입력부터 실행해요. 생략하면 에이전트의 첫 메시지 설정을 따르고, 설정에 따라 첫 대화 내역이 비어 있을 수 있어요.

사용자 메시지 보내기

POST /v3/chats/{chat_id}/messages로 보내세요. 같은 채팅의 응답을 받은 뒤 다음 메시지를 보내세요.

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"가 있어요. 이후 대화는 상세 조회로 확인하세요.

대화 내역 불러오기

GET /v3/chats/{chat_id}로 조회하세요. 화면을 다시 열 때 저장된 대화를 복원할 수 있어요.

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 타임스탬프예요.

채팅 끝내기

POST /v3/chats/{chat_id}/end로 끝내세요.

curl -X POST "https://client-api.tryvox.co/v3/chats/$CHAT_ID/end" \
  -H "Authorization: Bearer $VOX_API_KEY"

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

응답 읽기

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

{
  "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과 이번 응답에서 생긴 항목을 받아요.

{
  "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를 지정하세요.

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까지예요.

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

file_key는 API 참조의 파일 그룹에 있는 파일 업로드(POST /files)에서 받은 값으로 바꾸세요.

중복 요청 막기

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

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

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

연결 확인

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

문제가 생겼을 때

메시지를 보내면 CHAT_BUSY 오류가 나요

앞 메시지의 응답을 받은 뒤 다시 보내세요. 같은 채팅의 이전 메시지를 아직 처리하고 있다는 뜻이에요.

CHAT_ENDED나 CHAT_CHANNEL_OPERATION_UNSUPPORTED 오류가 나요

CHAT_ENDED가 나면 새 상담은 채팅을 새로 만들어 시작하세요. 이미 끝난 채팅이라는 뜻이에요. CHAT_CHANNEL_OPERATION_UNSUPPORTED가 나면 그 채팅의 채널이 api인지 확인하세요.

CHAT_NOT_FOUND 오류가 나요

채팅 ID와, API 키가 속한 워크스페이스를 확인하세요.

429나 RATE_LIMIT_EXCEEDED 오류가 나요

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

시작하기

구축

배포

발신

모니터링

설정

정책

준비물

채팅 연결하기

응답 읽기

채팅 목록 조회하기

이미지 보내기

중복 요청 막기

연결 확인

문제가 생겼을 때

관련 문서

​준비물

​채팅 연결하기

​응답 읽기

​채팅 목록 조회하기

​이미지 보내기

​중복 요청 막기

​연결 확인

​문제가 생겼을 때

​관련 문서

준비물

채팅 연결하기

응답 읽기

채팅 목록 조회하기

이미지 보내기

중복 요청 막기

연결 확인

문제가 생겼을 때

관련 문서