Sidetalk사용자 가이드
사이드톡 홈페이지 ↗대시보드 열기

대화 내역 조회 API

목적

이 API는 저장된 대화 이력(로그) 목록을 조회합니다. 검색어, 날짜 기간, 회원 ID 등을 기준으로 필터링할 수 있으며 페이징(Pagination)을 지원합니다.

URL


HTTP 메서드

GET

헤더

헤더값설명
Content-Typeapplication/json요청 본문이 JSON 형식임을 나타냅니다.
AuthorizationBearer <api_key>Sidetalk 대시보드에서 설치하기 메뉴에 제공된 API 키를 사용하세요.

파라미터 (Query String)

URL의 쿼리 스트링으로 전달되는 파라미터입니다.
파라미터타입필수설명
keywordString아니요질문 또는 답변 내용에 포함된 검색어입니다.
startDateString아니요조회 시작 일시입니다. (형식: YYYYMMDDHHmmss, 예: 20240101000000)
endDateString아니요조회 종료 일시입니다. (형식: YYYYMMDDHHmmss, 예: 20240131235959)
memberIdString아니요특정 회원의 대화만 조회할 경우 사용합니다.
pageNumber아니요조회할 페이지 번호입니다. 기본값은 1입니다.
limitNumber아니요한 페이지당 조회할 항목의 개수입니다. 기본값은 20입니다.
sortString아니요정렬 순서입니다. 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)
필드타입설명
currentPageNumber현재 조회한 페이지 번호입니다.
perPageNumber페이지당 조회된 항목 수입니다.
totalCountNumber검색 조건에 맞는 전체 데이터 개수입니다.
totalPagesNumber전체 페이지 수입니다.
2. 데이터 목록 (data)
필드타입설명
sessionIdString대화 세션의 고유 식별자입니다.
memberIdString질문한 회원의 ID입니다. (비회원인 경우 null 또는 빈 값일 수 있음)
questionString사용자가 입력한 질문 내용입니다.
answerStringAI가 응답한 답변 내용입니다.
statusString대화 처리 상태입니다. (예: success, fail)
channelString대화가 발생한 채널입니다. (예: chat, kakao, api)
hasImagesBoolean질문에 이미지가 포함되었는지 여부입니다.
createdAtString대화가 생성된 일시입니다.
imageUrlsArray<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 누락 등)"
}

오류 응답 필드 설명

필드타입설명
errorString발생한 오류에 대한 상세 정보입니다.