Skip to main content
POST
채팅 생성

Authorizations

Authorization
string
header
required

워크스페이스 API 키를 Authorization: Bearer <token> 형식으로 보냅니다.

Headers

Idempotency-Key
string
required

상태를 변경하는 POST 요청에 필요한 멱등성 키입니다. 24시간 동안 안전하게 재시도할 때 사용합니다. 값은 비어 있으면 안 됩니다. 최대 255자까지 허용합니다.

Required string length: 1 - 255

Body

application/json

채팅을 처리할 에이전트와 초기 설정입니다.

agent
AgentMapping · object
required

agent_id와 agent_version으로 구성된 에이전트 매핑 객체입니다.

metadata
Metadata · object

저장용 메타데이터입니다. 에이전트 처리에는 사용하지 않습니다.

dynamic_variables
Dynamic Variables · object

에이전트 프롬프트에 주입할 동적 변수입니다.

external_id
string | null

고객 식별용 external_id입니다. 지정하면 이 값으로 고객을 찾거나 새로 만들어 채팅을 그 고객에 연결합니다.

Required string length: 1 - 255
opening_message
string | null

첫 메시지로 쓸 문구입니다. 지정하면 에이전트의 첫 메시지 설정보다 우선하며, 에이전트는 첫 사용자 입력부터 실행됩니다.

Minimum string length: 1
initial_responder_type
enum<string>
default:agent

새 채팅의 최초 응답 담당입니다. agent는 AI 에이전트가 답합니다. external은 고객사 시스템이 맡아 AI의 첫 메시지와 AI 턴을 실행하지 않으며, opening_message는 안내 메시지로만 저장합니다. desk는 vox.ai 상담 화면용 값이므로 사용하지 않습니다.

Available options:
agent,
desk,
external

Response

성공 응답

id
string<uuid>
required

채팅 ID입니다.

customer_id
string<uuid> | null
required

고객 UUID입니다. 식별자 없이 만든 채팅에도 익명 고객이 생성되어 채워집니다. 오래된 채팅에서만 null일 수 있습니다.

agent
AgentMapping · object
required

agent_id와 agent_version으로 구성된 에이전트 매핑 객체입니다.

channel
string
required

채팅 채널입니다. api, widget, sms, kakao, navertalk, instagram, line, wechat, channeltalk 중 하나이며 등록된 채널 이름을 그대로 반환합니다.

Pattern: ^[a-z][a-z0-9_]{0,31}$
status
enum<string>
required

채팅 상태입니다.

Available options:
active,
ended
responder_type
enum<string>
required

채팅의 현재 응답 담당입니다. agent는 AI 에이전트, external은 고객사 시스템이나 사람, desk는 vox.ai 상담 화면의 상담사입니다. agent여도 채널 쪽 응대 주체에 따라 AI가 답하지 않을 수 있습니다.

Available options:
agent,
desk,
external
responder
ChatResponderResponse · object
required

현재 채팅 응답 담당입니다.

metadata
Metadata · object
required

생성 시 전달한 저장용 메타데이터입니다. 보존 정책으로 지우면 빈 객체입니다.

dynamic_variables
Dynamic Variables · object
required

생성 시 전달한 동적 변수입니다. 보존 정책으로 지우면 빈 객체입니다.

start_at
integer
required

채팅 시작 시각입니다(unix ms).

end_at
integer | null
required

채팅 종료 시각입니다(unix ms). active 상태에서는 null입니다.

chat_analysis
ChatAnalysisResponse · object | null
required

대화 종료 후 분석 결과입니다. 분석 완료 전에는 null 입니다.

chat_cost
ChatCostResponse · object | null
required

종료된 채팅의 청구 기록 기준 AI 사용료입니다. active 상태이거나 답변의 청구 기록을 확인할 수 없으면 null입니다. 답변 없는 실행의 LLM 사용료는 과금 처리 후 추가될 수 있습니다.

allow_agent_response
boolean | null
required

이 채팅에 지금 적용되는 채널의 AI 사용 허용 여부입니다(읽기 전용). 채널 설정을 조회 시점에 읽습니다. false이면 응답 담당이 AI여도 이후 입력에 AI가 답하지 않습니다. 설정을 확인할 수 없는 채팅도 false입니다. 채널 설정 대상이 아닌 채팅(API로 직접 만든 채팅, 수신 채널 설정이 없는 SMS 채팅)은 null입니다.

transcript
(ChatTranscriptMessageResponse · object | ChatToolCallInvocationResponse · object | ChatToolCallResultResponse · object)[]
required

채팅 대화록입니다. user/agent 메시지와 tool_call_invocation/tool_call_result 항목을 순서대로 포함합니다.

provider_responder
enum<string> | null

채널 쪽에 응대 주체가 따로 있는 채팅에서, 조회 시점에 채널이 알려 준 응대 주체입니다. 해당하지 않는 채팅은 null입니다.

Available options:
ai,
external,
unknown