대화 내역 조회 API
목적
이 API는 저장된 대화 이력(로그) 목록을 조회합니다. 검색어, 날짜 기간, 회원 ID 등을 기준으로 필터링할 수 있으며 페이징(Pagination)을 지원합니다.
URL
HTTP 메서드
GET
헤더
| 헤더 | 값 | 설명 |
| Content-Type | application/json | 요청 본문이 JSON 형식임을 나타냅니다. |
| Authorization | Bearer <api_key> | Sidetalk 대시보드에서 설치하기 메뉴에 제공된 API 키를 사용하세요. |
파라미터 (Query String)
URL의 쿼리 스트링으로 전달되는 파라미터입니다.
| 파라미터 | 타입 | 필수 | 설명 |
| keyword | String | 아니요 | 질문 또는 답변 내용에 포함된 검색어입니다. |
| startDate | String | 아니요 | 조회 시작 일시입니다. (형식: YYYYMMDDHHmmss, 예: 20240101000000) |
| endDate | String | 아니요 | 조회 종료 일시입니다. (형식: YYYYMMDDHHmmss, 예: 20240131235959) |
| memberId | String | 아니요 | 특정 회원의 대화만 조회할 경우 사용합니다. |
| page | Number | 아니요 | 조회할 페이지 번호입니다. 기본값은 1입니다. |
| limit | Number | 아니요 | 한 페이지당 조회할 항목의 개수입니다. 기본값은 20입니다. |
| sort | String | 아니요 | 정렬 순서입니다. desc(최신순) 또는 asc(과거순). 기본값은 desc입니다. |
요청 예시
Shell
curl -X GET "https://api.sidetalk.ai/v1/chat/logs?page=1&limit=10&keyword=${keyword}\
-H "Authorization: Bearer ${API_KEY}"응답 형식
응답은 JSON 형식으로 제공되며, 페이징 정보(meta)와 실제 데이터 목록(data)을 포함합니다.
응답 본문
JSON
{
"meta": {
"currentPage": 1,
"perPage": 10,
"totalCount": 125,
"totalPages": 13
},
"data": [
{
"sessionId": "sess_abc12345",
"memberId": "user_id",
"question": "환불 규정이 어떻게 되나요?",
"answer": "환불은 구매 후 7일 이내에 가능합니다.",
"status": "success",
"channel": "chat", // chat, kakao, api
"hasImages": true,
"createdAt": "20240126143000",
"imageUrls": [
"https://api.sidetalk.ai/v1/images/example1.jpg",
"https://api.sidetalk.ai/v1/images/example2.jpg"
]
}
]
}응답 필드 설명
1. Meta 정보 (meta)
| 필드 | 타입 | 설명 |
| currentPage | Number | 현재 조회한 페이지 번호입니다. |
| perPage | Number | 페이지당 조회된 항목 수입니다. |
| totalCount | Number | 검색 조건에 맞는 전체 데이터 개수입니다. |
| totalPages | Number | 전체 페이지 수입니다. |
2. 데이터 목록 (data)
| 필드 | 타입 | 설명 |
| sessionId | String | 대화 세션의 고유 식별자입니다. |
| memberId | String | 질문한 회원의 ID입니다. (비회원인 경우 null 또는 빈 값일 수 있음) |
| question | String | 사용자가 입력한 질문 내용입니다. |
| answer | String | AI가 응답한 답변 내용입니다. |
| status | String | 대화 처리 상태입니다. (예: success, fail) |
| channel | String | 대화가 발생한 채널입니다. (예: chat, kakao, api) |
| hasImages | Boolean | 질문에 이미지가 포함되었는지 여부입니다. |
| createdAt | String | 대화가 생성된 일시입니다. |
| imageUrls | Array<String> | 질문에 포함된 이미지의 조회 URL 목록입니다. 이미지가 없는 경우 빈 배열([])이 반환 됩니다. ※ 이미지 URL은 API 요청 후 10분간 유효합니다. 이미지를 반드시 따로 저장해주세요. |
예시 코드 (JavaScript)
대화 이력 조회
JavaScript
async function getChatLogs(page = 1, keyword = "") {
const baseUrl = "https://api.sidetalk.ai/v1/chat/logs";
// 쿼리 파라미터 구성
const params = new URLSearchParams({
page: page,
limit: 20,
sort: "desc"
});
if (keyword) params.append("keyword", keyword);
// 필요 시 startDate, endDate, memberId 추가 가능
try {
const response = await fetch(`${baseUrl}?${params.toString()}`, {
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer [API_KEY]"
}
});
if (!response.ok) {
const errorData = await response.json();
console.error("Server Error:", errorData.error || 'Unknown error');
return;
}
const result = await response.json();
console.log(`Total Logs: ${result.meta.totalCount}`);
result.data.forEach(log => {
console.log(`[${log.createdAt}] Q: ${log.inputQuestion} / A: ${log.responseAnswer}`);
if (log.hasImages) {
console.log("Images:", log.imageUrls);
}
});
} catch (error) {
console.error("Error fetching chat logs:", error);
}
}오류 응답
요청 처리 중 오류가 발생한 경우, 다음과 같은 응답이 반환됩니다.
응답 본문
JavaScript
{
"error": "잘못된 요청입니다. (site_id 누락 등)"
}오류 응답 필드 설명
| 필드 | 타입 | 설명 |
| error | String | 발생한 오류에 대한 상세 정보입니다. |
