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

고객사 서비스에서 사용하는 고객 식별자입니다. 지정하면 해당 식별자의 고객을 찾거나 생성해 채팅에 연결합니다.

Required string length: 1 - 255
opening_message
string | null

이 채팅의 첫 안내 메시지입니다. 지정하면 에이전트의 첫 메시지 설정보다 우선합니다. 에이전트는 첫 사용자 입력부터 실행합니다.

Minimum string length: 1

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를 지원하며 등록된 채널 이름을 그대로 반환합니다.

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

채팅 상태입니다.

Available options:
active,
ended
responder
ChatResponderResponse · object
required

현재 응답 주체입니다. AI, 상담사, 외부 채널 가운데 어느 쪽이 응답 중인지 확인합니다.

metadata
Metadata · object
required

생성 시 전달한 저장용 메타데이터입니다.

dynamic_variables
Dynamic Variables · object
required

생성 시 전달한 동적 변수입니다.

start_at
integer
required

채팅 시작 시각입니다. 밀리초 단위 Unix 타임스탬프입니다.

end_at
integer | null
required

채팅 종료 시각입니다. 밀리초 단위 Unix 타임스탬프이며 진행 중에는 null입니다.

chat_analysis
ChatAnalysisResponse · object | null
required

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

chat_cost
ChatCostResponse · object | null
required

확정된 Chat AI 사용료입니다. active 상태이거나 전체 비용을 확정할 수 없으면 null입니다.

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

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

provider_responder
enum<string> | null

외부 채널 응대권의 조회 시점 상태입니다. 채널 원장에서 계산하며 별도로 저장하지 않습니다.

Available options:
ai,
external,
unknown