Quickchat AI는 Widget, Slack, WhatsApp, Telegram 등 모든 채널에서 에이전트가 나눈 대화를 자동으로 기록하고 분석합니다. Conversations API는 이 풍부한 데이터에 프로그램 방식으로 접근하여 맞춤 대시보드, 분석 파이프라인, CRM 워크플로, 기존 비즈니스 인텔리전스 도구와의 연동을 만들 수 있게 합니다.
모든 대화에는 AI 기반 감정 감지, 주제 분류, 해결 상태 추적, 사람의 주의가 필요할 수 있는 대화의 자동 표시가 포함됩니다. 전체 메시지 기록, 링크 클릭 추적, 사용자 지정 메타데이터와 함께 방문자가 AI 에이전트와 어떻게 상호작용하는지 이해하는 데 필요한 정보를 제공합니다.
대화 데이터는 여러 엔드포인트로 나뉩니다.
- 대화 목록: 기본 정보, 방문자 정보, 상태. 대시보드, 개요, 필터 조회에 사용합니다.
- 대화 상세 조회:
unified_analysis(AI 생성 인사이트)와client_metadata를 포함한 전체 정보. - 대화 이벤트 조회: 전체 메시지 기록, 추적한 링크 클릭, 로그 항목.
- 메타데이터 조회/설정: 대화에 첨부하는 사용자 지정 키-값 데이터(대화 메타데이터 참고).
대화 목록
섹션 제목: “대화 목록”GET https://app.quickchat.ai/v1/api_core/conversations
쿼리 매개변수
| 매개변수 | 설명 |
|---|---|
limit 정수 | 페이지당 항목 수 |
offset 정수 | 건너뛸 항목 수 |
query 문자열 | 순번, UUID 또는 메시지 텍스트로 검색 |
assignee_type 문자열 | "ai_assistant", "human_operator", "unassigned" |
source 문자열 | "widget", "slack", "telegram", "whatsapp" 등 |
resolution_status 문자열 | "open" 또는 "resolved" |
created_timestamp_start_date 날짜/시간 | 생성일 필터(시작) |
created_timestamp_end_date 날짜/시간 | 생성일 필터(끝) |
last_message_at_start_date 날짜/시간 | 마지막 메시지 일시 필터(시작) |
last_message_at_end_date 날짜/시간 | 마지막 메시지 일시 필터(끝) |
most_frequent_language 문자열 | 감지된 언어로 필터링 |
order 문자열 | "desc"(기본값, 최신순) 또는 "asc"(오래된 순). 오름차순은 알려진 대화부터 앞으로 탐색할 때 사용하므로 last_message_at_start_date와 함께 지정하세요. |
curl 'https://app.quickchat.ai/v1/api_core/conversations?limit=10&resolution_status=open' \ -H 'Authorization: Bearer <API_TOKEN>'import requests
response = requests.get( url="https://app.quickchat.ai/v1/api_core/conversations", headers={"Authorization": "Bearer <API_TOKEN>"}, params={"limit": 10, "resolution_status": "open"},)data = response.json()응답 200 OK
{ "items": [ { "id": "conv-uuid-1234", "ord": 42, "created_at": "2026-01-15T10:30:00Z", "last_message_at": "2026-01-15T10:35:00Z", "title": "Return policy question", "source": "widget", "terminated": false, "resolution_status": "open", "has_unread_messages": true, "supports_inbox_control": true, "last_message_content": "What is your return policy?", "most_frequent_language": "en", "assignee": { "type": "ai_assistant" }, "visitor_name": "John", "visitor_email": "john@example.com", "visitor_phone_number": null, "visitor_label": null } ], "offset": 0, "limit": 10, "count": 42}| 필드 | 설명 |
|---|---|
id 문자열 | 대화 UUID |
ord 정수 | 순차 대화 번호 |
created_at 문자열 | 대화 생성 타임스탬프 |
last_message_at 문자열 | 가장 최근 메시지의 타임스탬프 |
title 문자열 | AI가 생성한 대화 제목 |
source 문자열 | 대화가 시작된 채널(예: "widget", "slack", "whatsapp") |
terminated 불리언 | 대화 종료 여부 |
resolution_status 문자열 | "open" 또는 "resolved" |
has_unread_messages 불리언 | 읽지 않은 메시지 존재 여부 |
supports_inbox_control 불리언 | 대화 소스가 받은편지함 제어(배정, 전달)를 지원하는지 여부 |
last_message_content 문자열 | 대화의 마지막 메시지 내용 |
most_frequent_language 문자열 | 대화에서 가장 자주 감지된 언어 |
assignee 객체 | 현재 담당자(type: "ai_assistant", "human_operator", "unassigned") |
visitor_name 문자열 또는 null | 방문자 이름(채팅 전 양식 또는 채널 프로필에서 수집) |
visitor_email 문자열 또는 null | 방문자 이메일 주소 |
visitor_phone_number 문자열 또는 null | 방문자 전화번호 |
visitor_label 문자열 또는 null | 방문자에게 지정한 사용자 지정 라벨 |
대화 상세 조회
섹션 제목: “대화 상세 조회”GET https://app.quickchat.ai/v1/api_core/conversations/{conversation_id}/
curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/ \ -H 'Authorization: Bearer <API_TOKEN>'import requests
response = requests.get( url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/", headers={"Authorization": "Bearer <API_TOKEN>"},)data = response.json()응답 200 OK
{ "id": "conv-uuid-1234", "ord": 42, "created_at": "2026-01-15T10:30:00Z", "last_message_at": "2026-01-15T10:35:00Z", "title": "Return policy question", "source": "widget", "terminated": false, "resolution_status": "open", "has_unread_messages": true, "supports_inbox_control": true, "last_message_content": "What is your return policy?", "most_frequent_language": "en", "assignee": { "type": "ai_assistant" }, "url": null, "client_metadata": {"userId": 12}, "last_visitor_message_at": "2026-01-15T10:34:00Z", "unified_analysis": { "sentiment": "neutral", "resolution_status": "open", "topic": "Return policy", "is_flagged": false, "flag_reason": null }, "visitor_name": "John", "visitor_email": "john@example.com", "visitor_phone_number": null, "visitor_label": null}상세 응답에는 목록 응답의 모든 필드와 다음 항목이 포함됩니다.
| 필드 | 설명 |
|---|---|
url 문자열 또는 null | 대화를 시작한 페이지 URL(Widget 전용) |
client_metadata 객체 또는 null | 대화에 첨부한 사용자 지정 키-값 쌍 |
last_visitor_message_at 문자열 | 마지막 방문자 메시지의 타임스탬프 |
unified_analysis 객체 또는 null | AI가 생성한 대화 분석(아래 참고) |
unified_analysis 필드:
| 필드 | 설명 |
|---|---|
sentiment 문자열 | AI가 감지한 대화 감정(예: "positive", "neutral", "negative") |
resolution_status 문자열 | AI가 평가한 해결 상태(최상위 resolution_status와 다를 수 있음) |
topic 문자열 | AI가 감지한 대화 주제 |
is_flagged 불리언 | 사람의 검토를 위해 AI가 대화를 표시했는지 여부 |
flag_reason 문자열 또는 null | 대화에 표시한 이유 |
최상위 resolution_status 필드("open" 또는 "resolved")는 수동 또는 자동화 규칙으로 설정하는 공식 상태입니다.
unified_analysis.resolution_status는 AI 분석으로 계산하며 다를 수 있습니다. 예를 들어 최상위 상태가 "open"이어도 내용 분석상 해결된 것으로 분류할 수 있습니다. 필터와 워크플로에는 최상위 필드를, 분석과 인사이트에는 unified_analysis를 사용하세요.
대화 이벤트 조회
섹션 제목: “대화 이벤트 조회”대화의 모든 이벤트(메시지, 추적 링크, 로그)를 조회합니다.
권한 범위: read_allGET https://app.quickchat.ai/v1/api_core/conversations/{conversation_id}/events/
쿼리 매개변수
| 매개변수 | 설명 |
|---|---|
limit 정수 | 페이지당 항목 수 |
offset 정수 | 건너뛸 항목 수 |
curl 'https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/events/?limit=20' \ -H 'Authorization: Bearer <API_TOKEN>'import requests
response = requests.get( url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/events/", headers={"Authorization": "Bearer <API_TOKEN>"}, params={"limit": 20},)data = response.json()응답 200 OK
{ "items": [ { "type": "message", "data": { "id": "msg-uuid-001", "ord": 1, "created_at": "2026-01-15T10:30:00Z", "content": "Hello! How can I help you today?", "author": "ai_assistant", "handoff_state": null, "message_insights": null, "feedback": null, "client_metadata": null, "sources_generated": [], "is_welcome": true, "attachments": [] } }, { "type": "message", "data": { "id": "msg-uuid-002", "ord": 2, "created_at": "2026-01-15T10:31:00Z", "content": "What is your return policy?", "author": "visitor", "handoff_state": null, "message_insights": null, "feedback": null, "client_metadata": null, "sources_generated": [], "is_welcome": false, "attachments": [] } } ], "offset": 0, "limit": 20, "count": 2}이벤트 유형: message, tracked_link, log
작성자 유형: ai_assistant, visitor, human_operator
| 필드 | 설명 |
|---|---|
type 문자열 | 이벤트 유형: "message", "tracked_link", "log" |
data.id 문자열 | 메시지 고유 식별자 |
data.ord 정수 | 순차 메시지 번호 |
data.created_at 문자열 | 이벤트 타임스탬프 |
data.content 문자열 | 메시지 내용 |
data.author 문자열 | "ai_assistant", "visitor", "human_operator" |
data.handoff_state 문자열 또는 null | 해당하는 경우 전달 상태 |
data.message_insights 객체 또는 null | AI가 생성한 메시지 인사이트 |
data.feedback 객체 또는 null | 메시지에 대한 사용자 피드백 |
data.client_metadata 객체 또는 null | 메시지에 첨부한 사용자 지정 메타데이터 |
data.sources_generated 배열 | AI가 응답 생성에 사용한 지식 베이스 문서 |
data.is_welcome 불리언 | 환영 메시지인지 여부 |
data.attachments 배열 | 파일 첨부 |