Conversation History API

5 min readGuide reference date: October 14, 2026.View original in Notion ↗

Purpose

This API retrieves stored conversation logs. Filter by search term, date range, member ID, and more. Pagination is supported.

URL

HTTP method

GET

Headers

Headers	Value	Description
Content-Type	application/json	Indicates that the request body is JSON.
Authorization	Bearer <api_key>	Use the API key provided in Install in the Sidetalk dashboard.

Parameters (query string)

Parameters passed in the URL query string.

Parameter	Type	Required	Description
keyword	String	No	A search term contained in the question or answer.
startDate	String	No	Start date and time. (Format: YYYYMMDDHHmmss, example: 20240101000000)
endDate	String	No	End date and time. (Format: YYYYMMDDHHmmss, example: 20240131235959)
memberId	String	No	Used to retrieve conversations for a particular member only.
page	Number	No	The page number to retrieve. Defaults to 1.
limit	Number	No	Items per page. Defaults to 20.
sort	String	No	Sort order: desc (newest first) or asc (oldest first). Defaults to desc.

Example request

Shell


  curl -X GET "https://api.sidetalk.ai/v1/chat/logs?page=1&limit=10&keyword=${keyword}\
  -H "Authorization: Bearer ${API_KEY}"

Response format

The JSON response includes pagination information (meta) and the actual data list (data).

Response body

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"
      ]
    }
  ]
}

Response fields

1. Metadata (meta)

Field	Type	Description
currentPage	Number	The current retrieved page number.
perPage	Number	The number of items retrieved per page.
totalCount	Number	The total number of records matching the search criteria.
totalPages	Number	The total number of pages.

2. Data list (data)

Field	Type	Description
sessionId	String	The unique conversation session identifier.
memberId	String	The ID of the member who asked the question. (May be null or empty for a non-member.)
question	String	The question entered by the user.
answer	String	The answer returned by the AI.
status	String	Conversation processing status. (Examples: success, fail)
channel	String	The channel where the conversation occurred. (Examples: chat, kakao, api)
hasImages	Boolean	Whether the question included an image.
createdAt	String	The date and time the conversation was created.
imageUrls	Array<String>	A list of URLs for images included in the question. Returns an empty array ([]) if there are none. ※ Image URLs remain valid for 10 minutes after the API request. Be sure to save images separately.

Example code (JavaScript)

Retrieve conversation history

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);
    }
}

Error response

If an error occurs while processing the request, the following response is returned.

Response body

JavaScript

{
  "error": "잘못된 요청입니다. (site_id 누락 등)"
}

Error response fields

Field	Type	Description
error	String	Detailed information about the error.