How to Retrieve Shoply AI Chat History Through the API

Shoply AI’s admin page retrieves chat and search history through two authenticated API requests:

query_sessionized_chat returns a list of conversation summaries.
query_log_visualization returns the complete timeline for one selected conversation.

These are the same endpoints used by the Analytics → Chat & Search History page. They can also be called from your own backend. Unlike the product-search API, chat history is private merchant and customer data, so every request requires store-scoped authentication.

Authentication

Send the Authorization header as a JSON string with this shape:


{
  "store_key": "your-store.myshopify.com",
  "admin_auth_token": "YOUR_SHOPIFY_ADMIN_API_ACCESS_TOKEN"
}

This is not a Bearer header. The entire JSON value is placed directly in the Authorization header.

For a Shopify store, admin_auth_token must be a valid Shopify Admin API access token authorized for the same store as store_key. If you call the API from your own backend, use a token issued to your Shopify app or custom app.

Keep this token on your server. Never include it in public browser code, commit it to source control, write it to client-side logs, or expose it in a URL.

Step 1: Retrieve Conversation Summaries

Endpoint


GET https://api.shoplyai.ai/query_sessionized_chat

Query Parameters

Parameter	Required	Description
`store_key`	Yes	The store’s permanent `myshopify.com` domain
`start_dt_utc`	Yes	UTC start time as `YYYY-MM-DD HH:mm:ss`, or the literal value `undefined`
`end_dt_utc`	Yes	UTC end time as `YYYY-MM-DD HH:mm:ss`, or the literal value `undefined`
`num_sessions`	No	Number of sessions to select when either time bound is `undefined`
`ScanIndexForward`	No	Use `false` to select the newest sessions first; defaults to `true`

Retrieve the Latest 40 Conversations


curl --get "https://api.shoplyai.ai/query_sessionized_chat" \
  --header 'Authorization: {"store_key":"your-store.myshopify.com","admin_auth_token":"YOUR_SHOPIFY_ADMIN_API_ACCESS_TOKEN"}' \
  --data-urlencode "store_key=your-store.myshopify.com" \
  --data-urlencode "start_dt_utc=undefined" \
  --data-urlencode "end_dt_utc=undefined" \
  --data-urlencode "num_sessions=40" \
  --data-urlencode "ScanIndexForward=false"

Retrieve Conversation Summaries in a UTC Time Range

When both time bounds are provided, the API returns the sessions found in that range. num_sessions does not limit a fully bounded range.


curl --get "https://api.shoplyai.ai/query_sessionized_chat" \
  --header 'Authorization: {"store_key":"your-store.myshopify.com","admin_auth_token":"YOUR_SHOPIFY_ADMIN_API_ACCESS_TOKEN"}' \
  --data-urlencode "store_key=your-store.myshopify.com" \
  --data-urlencode "start_dt_utc=2026-07-28 00:00:00" \
  --data-urlencode "end_dt_utc=2026-07-28 23:59:59" \
  --data-urlencode "ScanIndexForward=false"

The timestamps must be UTC. The Shoply admin page converts the store’s selected local day or hour to UTC before making this request.

Summary Response


{
  "data": [
    {
      "customer_id": "customer-or-session-id",
      "user_questions": "Do you have this in blue?\nWhen will it ship?",
      "start_timestamp_ms": 1785196800000,
      "end_timestamp_ms": 1785196865000,
      "session_types": "product information, click",
      "customer_email": null,
      "customer_info": {},
      "sentiment": "positive",
      "num_questions": 2,
      "num_searches": 1,
      "num_clicks": 1
    }
  ]
}

Fields are included when available and may vary by conversation. In particular, customer email, geographic information, sentiment, and activity counters are optional.

The most important values for retrieving the full conversation are:

customer_id
start_timestamp_ms
end_timestamp_ms

Step 2: Retrieve One Complete Conversation

Use the selected summary to call the detail endpoint.

Endpoint


GET https://api.shoplyai.ai/query_log_visualization

Query Parameters

Parameter	Required	Description
`store_key`	Yes	The same permanent `myshopify.com` domain
`date_time_utc_start`	Yes	The summary start time formatted as UTC `YYYY-MM-DD HH:mm:ss`
`date_time_utc_end`	Yes	The summary end time formatted as UTC `YYYY-MM-DD HH:mm:ss`
`session_id`	No	Pass the summary’s `customer_id` for compatibility with older history records
`start_timestamp_ms`	Recommended	Pass the summary’s exact `start_timestamp_ms` to retrieve the composed session

cURL Example


curl --get "https://api.shoplyai.ai/query_log_visualization" \
  --header 'Authorization: {"store_key":"your-store.myshopify.com","admin_auth_token":"YOUR_SHOPIFY_ADMIN_API_ACCESS_TOKEN"}' \
  --data-urlencode "store_key=your-store.myshopify.com" \
  --data-urlencode "date_time_utc_start=2026-07-28 00:00:00" \
  --data-urlencode "date_time_utc_end=2026-07-28 00:01:05" \
  --data-urlencode "session_id=customer-or-session-id" \
  --data-urlencode "start_timestamp_ms=1785196800000"

Detail Response


{
  "data": [
    {
      "action_type": "QA",
      "session_id": "customer-or-session-id",
      "utc_date_time": "2026-07-28 00:00:00",
      "start_timestamp_ms": 1785196800000,
      "server_timestamp_ms": 1785196800123,
      "Q": {
        "question": "Do you have this in blue?",
        "question_context": {}
      },
      "task_id": "task-id",
      "list_tokens": [
        {
          "data_type": "LLMOutput",
          "data": "Yes. These blue options are currently available."
        }
      ],
      "dict_search_results": {}
    }
  ]
}

The data array is the conversation timeline. Depending on the session, it can contain:

Customer questions and AI answers
AI search blocks and recommended products
Product clicks
Add-to-cart events
Checkout events
Human-agent participant information

Use server_timestamp_ms when ordering mixed customer, AI, and commerce actions. Older records may have fewer fields.

JavaScript Backend Example


// Keep the Shopify Admin API token in a server-side environment variable.
const storeKey = "your-store.myshopify.com";
const authorization = JSON.stringify({
  store_key: storeKey,
  admin_auth_token: process.env.SHOPIFY_ADMIN_API_ACCESS_TOKEN
});
 
const summaryUrl = new URL("https://api.shoplyai.ai/query_sessionized_chat");
summaryUrl.search = new URLSearchParams({
  store_key: storeKey,
  start_dt_utc: "undefined",
  end_dt_utc: "undefined",
  num_sessions: "40",
  ScanIndexForward: "false"
}).toString();
 
const summaryResponse = await fetch(summaryUrl, {
  headers: {
    Authorization: authorization
  }
});
 
if (!summaryResponse.ok) {
  throw new Error(`Shoply history request failed with status ${summaryResponse.status}`);
}
 
const { data: sessions } = await summaryResponse.json();
console.log(sessions);

Python Backend Example


import json
import os
import requests
 
store_key = "your-store.myshopify.com"
 
# Keep the Shopify Admin API token in a server-side environment variable.
authorization = json.dumps({
    "store_key": store_key,
    "admin_auth_token": os.environ["SHOPIFY_ADMIN_API_ACCESS_TOKEN"],
})
 
response = requests.get(
    "https://api.shoplyai.ai/query_sessionized_chat",
    headers={"Authorization": authorization},
    params={
        "store_key": store_key,
        "start_dt_utc": "undefined",
        "end_dt_utc": "undefined",
        "num_sessions": 40,
        "ScanIndexForward": "false",
    },
    timeout=30,
)
response.raise_for_status()
 
sessions = response.json()["data"]
print(sessions)

Privacy, Retention, and Error Handling

Shoply AI’s standard chat and search history retention period is 90 days. History older than the configured retention window is deleted.
Responses may contain personal data, including customer identifiers, email addresses, approximate location, questions, and shopping activity. Store and process it according to your privacy policy and applicable law.
Return only the fields your application needs, and avoid caching history indefinitely.
HTTP 403 means the token is missing, expired, invalid, or does not belong to the requested store.
Use bounded UTC ranges for exports or recurring jobs so responses remain manageable.
Site Chat accounts use their authenticated Shoply human-agent access token instead of a Shopify Admin API access token.

For help with an integration that requires custom authentication, exports, or retention requirements, contact Shoply AI.