대화

자체 앱이나 고객 서비스 시스템에서 AI와 대화할 수 있으며, 스트리밍 응답과 세션의 상담원 연결, 종료 및 평가를 지원합니다.

POST /v1/chat

{
  "message": "有没有 400 美元以内的潜水表？",
  "conversation_id": null,
  "user": {"id": "u_123", "name": "李四", "email": "li@example.com", "ip": "85.214.132.117", "language": null},
  "stream": false
}

conversation_id를 보내지 않으면 새 세션이 생성되고, 응답에서 이 값을 반환하니 이후 메시지에 함께 보내세요.
user는 여러분의 서버가 직접 알려주는 정보입니다(API Key 호출자는 신뢰할 수 있는 주체입니다). 이 정보를 보내야만 주문을 조회할 수 있습니다.
기본 답변 언어: user.language(예: de, zh-CN, pt-BR)를 보내면 해당 언어를 사용합니다. 그렇지 않으면 user.ip를 보내주세요. 저희가 위치를 기준으로 판단합니다. 둘 다 보내지 않으면 관리자 페이지의 기본 언어를 사용합니다. 대화 중 고객이 언어 변경을 요청하면 고객의 요청을 우선합니다.
stream: false이면 {"conversation_id", "message", "status", "products"}를 반환합니다. message가 null이면 세션이 상담원 응대 중이고 메시지가 상담원에게 전달되었다는 뜻입니다.
stream: true이면 SSE로 반환하며, 이벤트는 아래 표를 참고하세요.

이벤트 `type`	내용
`user_message`	저장된 사용자 메시지
`delta`	답변의 텍스트 조각 `text`, 순서대로 이어 붙입니다
`products`	AI가 조회한 상품 카드
`language`	고객이 답변 언어 변경을 요청한 경우, `language`는 새로운 언어 코드입니다
`status`	세션 상태 변경(예: 상담원 연결)
`replace`	`text`로 지금까지 받은 답변을 통째로 교체합니다(오류 시 대체 안내 문구로 교체)
`queued_for_human`	세션이 상담원 응대 중이라 AI 답변이 없음
`done`	최종 저장된 메시지와 세션 상태
`error`	오류 발생

기타 API

메서드	경로	설명
GET	`/v1/conversations`	세션 목록, `?status=&end_user_id=`
GET	`/v1/conversations/{id}/messages`	세션과 전체 메시지
POST	`/v1/conversations/{id}/messages`	여러분의 상담 시스템이 상담원 자격으로 답변: `{"content", "agent_name"}`, 세션이 곧바로 상담원 응대 상태로 전환됩니다
POST	`/v1/conversations/{id}/status`	상담원 측 조작: `{"status": "ai"}`는 AI에게 되돌리기, `{"status": "closed"}`는 세션 종료
POST	`/v1/conversations/{id}/close`	고객이 여러분의 앱에서 세션을 종료합니다. 이미 종료된 경우에도 성공을 반환합니다
POST	`/v1/conversations/{id}/rating`	세션 종료 후 고객 평가: `{"rating": "good" \| "bad", "comment": "선택 사항, 최대 500자"}`, 변경할 수 있습니다

세션 상태: ai(AI 답변), pending_human(상담원 대기), human(상담원 응대 중), closed(종료됨).

세션에는 그 밖에 closed_by(누가 종료했는지 — customer 고객, agent 상담원, ai 고객이 더 이상 문의가 없다고 밝힌 뒤 AI가 종료), rating / rating_comment / rated_at(고객 평가)이 있습니다.

세션 종료: 웹 위젯 상단에 「세션 종료」 버튼이 있습니다(한 번 더 확인). WeChat 미니프로그램에서는 고객이 「종료」를 보내도 세션이 종료됩니다. 「봇 설정」에서 「AI 자동 세션 종료」를 켜면 고객이 더 이상 문의가 없다고 명확히 밝혔을 때 AI가 인사말을 남기고 세션을 종료합니다. 종료 후 웹 위젯에서는 고객에게 만족 / 불만족 평가와 추가 의견 작성을 요청하고, WeChat에서는 1 또는 2로 답변해 달라고 안내합니다. 이후 고객이 메시지를 보내면 새로운 세션이 시작됩니다.

상담원 연결 후 배정: 「봇 설정」에서 배정 방식을 선택합니다. 진행 중인 세션이 가장 적은 상담원에게 배정(기본값), 순번대로 배정, 또는 상담원이 직접 받기 중에서 고릅니다. 자동 배정은 「온라인」으로 설정하고 관리자 페이지를 열어둔 상담원에게만 이루어지며, 상담원마다 동시 응대 가능한 세션 수 상한이 있습니다(「팀」 페이지에서 설정). 배정된 상담원이 정해진 시간(기본 2분) 안에 응답하지 않으면 다시 배정됩니다. 세션의 assigned_member_id는 배정된 상담원, assigned_at은 배정 시각, handoff_at은 상담원 연결 시각입니다. 상담원이 모두 가득 차면 고객은 대기열에 서게 되고, 웹 위젯에는 앞에 몇 명이 남았는지 표시됩니다.

영업시간과 메시지 남기기: 「봇 설정」에서 영업시간을 켜면 영업시간 외에 고객이 상담원 연결을 요청해도 대기열에 서지 않고, 웹 위젯에 메시지 남기기 양식(호칭, 이메일 또는 휴대폰 번호, 문의 내용)이 표시됩니다. WeChat과 Open API 대화에서는 AI가 고객에게 메시지를 남겨 달라고 안내합니다. 영업시간 내라도 온라인 상담원이 없으면 마찬가지입니다. 남긴 메시지는 티켓으로 생성되며, 상담원이 답변할 때 원래 세션이 아직 종료되지 않았다면 그 세션으로 전송되고, 고객이 이메일을 남겼다면 스토어 이름으로 이메일도 발송됩니다. 여러분의 시스템으로만 전달하는 경우(상담원 연결 방식에서 「내 시스템으로 푸시」 선택)에는 영업시간이 적용되지 않습니다.

이 페이지가 도움이 되었나요?

마지막 업데이트: 2026년 10월 31일