วิธีใช้ Shoply Merchant API

Shoply Merchant API ช่วยให้ร้านค้าสามารถใช้ข้อมูล Shoply ของตนเองได้อย่างปลอดภัยในเครื่องมือรายงาน เวิร์กโฟลว์การสนับสนุน การส่งออกตามกำหนดเวลา และแอปพลิเคชันธุรกิจภายในแบบส่วนตัว

การเชื่อมต่อแต่ละรายการจะยืนยันตัวตนด้วยข้อมูลรับรองแบบเพิกถอนได้ซึ่งผูกกับร้านค้า และสร้างใน Shoply Settings คุณไม่จำเป็นต้องแชร์ Shopify Admin API access token และการเชื่อมต่อจะเข้าถึงได้เฉพาะร้านค้าที่ออกข้อมูลรับรองนั้นเท่านั้น

ฉันสามารถทำอะไรได้บ้างด้วย Merchant API?

คุณสามารถใช้ Merchant API เพื่อ:

• ส่งออกผลลัพธ์ประสิทธิภาพรายวัน รายสัปดาห์ หรือรายเดือนไปยังสเปรดชีตหรือคลังข้อมูล
• สร้างแดชบอร์ดส่วนตัวสำหรับ sessions, chats, searches, product clicks, add-to-cart events, purchases และ attributed revenue
• ติดตามกิจกรรมของลูกค้าและค้นหาความเปลี่ยนแปลงที่ผิดปกติของการมีส่วนร่วม
• ตรวจสอบเซสชันแชตและการค้นหาสำหรับงานด้านซัพพอร์ต การจัดการสินค้า และคุณภาพของคำตอบ
• ดึงไทม์ไลน์ของบทสนทนาแต่ละรายการเมื่อตรวจสอบปัญหาของลูกค้า
• สร้าง อัปเดต แสดงรายการ และลบ custom knowledge ที่ Shoply AI ใช้งาน
• เพิ่มหน้าเว็บภายนอกหรือไฟล์ PDF, text หรือ Markdown ที่อัปโหลดเข้าไปยัง knowledge base
• ปรับข้อมูลอีเวนต์แบบ UTC ให้ตรงกับเขตเวลาท้องถิ่นของร้านค้า

คู่มือนี้อธิบาย 7 endpoints โดย 5 endpoints เป็น endpoints เดียวกับที่ใช้ใน Shoply Admin → Analytics ขณะที่อีก 2 endpoints ใช้จัดการ knowledge base:

response bodies ด้านล่างเป็นเพียงตัวอย่างอ้างอิง ฟิลด์และค่าจริงของคุณจะสะท้อนกิจกรรมที่ถูกบันทึกไว้สำหรับร้านค้าของคุณ

ข้อกำหนดด้าน deployment: ต้องมีการ deploy การยืนยันตัวตนด้วย store-owner secret บน API server ที่คุณเรียกใช้ หาก secret ที่ถูกต้องส่งกลับ HTTP 403 พร้อม No access_token found แปลว่า server นั้นยังใช้โค้ดยืนยันตัวตนแบบเก่าที่รองรับเฉพาะ access token เท่านั้น

ฉันจะสร้าง API Secret ได้อย่างไร?

1. เปิดหน้าแอดมิน Shoply AI ของคุณ
2. ไปที่ Settings → Store owner API secret
3. สร้าง secret และตั้งชื่อที่บ่งบอกการเชื่อมต่อนั้น เช่น Weekly reporting export
4. คัดลอก secret ทันทีเมื่อแสดงขึ้นมา Shoply จะแสดงค่า plaintext เพียงครั้งเดียว

secret แต่ละรายการมีอายุใช้งาน 90 วัน ร้านค้าหนึ่งแห่งสามารถมี secret แยกสำหรับแต่ละการเชื่อมต่อได้ และคุณสามารถเพิกถอน secret หนึ่งรายการโดยไม่กระทบกับรายการอื่น

บันทึกค่าเหล่านี้เป็น environment variables ฝั่งเซิร์ฟเวอร์:

export SHOPLY_STORE_KEY="your-store.myshopify.com"
export SHOPLY_STORE_OWNER_API_SECRETE="shoply_owner_key_example123.secret-value"

สำหรับ SHOPLY_STORE_KEY ให้ใช้โดเมน myshopify.com ถาวรของร้านค้า แม้ว่าปกติลูกค้าจะเข้าชมผ่าน custom domain ก็ตาม

การยืนยันตัวตนทำงานอย่างไร?

ทุกคำขอของ Merchant API จะส่ง header Authorization โดยมีค่าเป็นสตริง JSON:

{
  "store_key": "your-store.myshopify.com",
  "store_owner_api_secrete": "YOUR_STORE_OWNER_API_SECRET"
}

store_owner_api_secrete คือชื่อฟิลด์สาธารณะที่ต้องใช้แบบตรงตัว รวมถึงการสะกดตามประวัติเดิมด้วย นี่ไม่ใช่ Bearer token ให้วางสตริง JSON ทั้งก้อนลงใน header Authorization โดยตรง

เก็บ secret ไว้ในโค้ด backend เท่านั้น อย่าใส่ไว้ใน URL, browser bundle, public repository, analytics event หรือ application log

มีแพ็กเกจ Python และ Node.js อย่างเป็นทางการหรือไม่?

มี Shoply เผยแพร่แพ็กเกจฝั่งเซิร์ฟเวอร์ 2 รายการที่เพิ่มการยืนยันตัวตนที่จำเป็นให้อัตโนมัติ และเปิดให้ใช้ Merchant API ผ่าน typed functions ทั้งสองแพ็กเกจเป็นโอเพนซอร์สภายใต้องค์กร GitHub shoplyai-public

Python Package

แพ็กเกจ shoply-merchant-api รองรับ Python 3.12 และใช้ Pydantic v2 response models ติดตั้ง release 2.1.3 ที่ pin ไว้:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install "git+https://github.com/shoplyai-public/shoply-merchant-api.git@v2.1.3"

ดึงเซสชันแชตและการค้นหาล่าสุดเป็น typed SessionSummary models:

import os
 
from shoply_merchant_api import ShoplyMerchantClient
 
 
with ShoplyMerchantClient(
    store_key=os.environ["SHOPLY_STORE_KEY"],
    api_secret=os.environ["SHOPLY_STORE_OWNER_API_SECRETE"],
) as shoply:
    session_response = shoply.list_sessions(limit=40)
 
for conversation in session_response.data:
    print(conversation.customer_id, conversation.user_questions)

แพ็กเกจนี้ยังมีฟังก์ชันสำหรับ analytics, activity counts, complete session timelines, store timezone และ knowledge management ดูเพิ่มเติมได้ที่ business-use-case guide  และ API reference 

Node.js and TypeScript Package

รีโพซิทอรี shoply-merchant-api-js มีแพ็กเกจ @shoplyai/merchant-api สำหรับ Node.js 20 ขึ้นไป เป็นแพ็กเกจ ESM ที่มี TypeScript declarations ในตัวและไม่มี runtime dependencies ติดตั้ง release 2.1.3 ที่ pin ไว้ได้โดยตรงจาก GitHub:

npm install "github:shoplyai-public/shoply-merchant-api-js#v2.1.3"

ดึงเซสชันล่าสุดชุดเดียวกันจากเซิร์ฟเวอร์ Node.js:

import { ShoplyMerchantClient } from "@shoplyai/merchant-api";
 
const storeKey = process.env.SHOPLY_STORE_KEY;
const apiSecret = process.env.SHOPLY_STORE_OWNER_API_SECRETE;
if (!storeKey || !apiSecret) {
  throw new Error("SHOPLY_STORE_KEY and SHOPLY_STORE_OWNER_API_SECRETE are required");
}
 
const shoply = new ShoplyMerchantClient({
  storeKey,
  apiSecret,
});
 
const sessionResponse = await shoply.listSessions({ limit: 40 });
 
for (const conversation of sessionResponse.data) {
  console.log(conversation.customer_id, conversation.user_questions);
}

แพ็กเกจ npm ครอบคลุม Merchant API endpoints ชุดเดียวกับแพ็กเกจ Python ดูเพิ่มเติมได้ที่ business-use-case guide  และ API reference 

ทั้งสองแพ็กเกจออกแบบมาสำหรับ backend services ที่เชื่อถือได้ งานตามกำหนดเวลา และเครื่องมือภายในแบบส่วนตัว อย่านำแพ็กเกจใดแพ็กเกจหนึ่งไป import ในโค้ด storefront หรือเปิดเผย API secret ใน browser bundle

ฉันสามารถเรียก HTTP API ได้โดยไม่ใช้แพ็กเกจหรือไม่?

ได้ Merchant API ยังคงเป็น HTTPS API มาตรฐาน ตัวอย่าง Python ระดับล่างด้านล่างใช้ Requests เพื่อให้คุณเห็น wire contract ทั้งหมด หรือเพื่อนำไปเชื่อมต่อจากภาษาอื่น

ติดตั้ง Requests หาก environment ของคุณยังไม่มี:

python -m pip install requests

helper ด้านล่างจะเพิ่ม store key และ authentication header ให้ทุกคำขอ:

import json
import os
from typing import Any
 
import requests
 
BASE_URL = "https://api.shoplyai.ai"
STORE_KEY = os.environ["SHOPLY_STORE_KEY"]
STORE_OWNER_API_SECRETE = os.environ["SHOPLY_STORE_OWNER_API_SECRETE"]
 
session = requests.Session()
session.headers.update({
    "Authorization": json.dumps({
        "store_key": STORE_KEY,
        "store_owner_api_secrete": STORE_OWNER_API_SECRETE,
    })
})
 
 
def shoply_get(api_name: str, **params: Any) -> dict[str, Any]:
    """Call one store-scoped Shoply API and surface HTTP or API-level errors."""
    response = session.get(
        f"{BASE_URL}/{api_name}",
        params={"store_key": STORE_KEY, **params},
        timeout=30,
    )
    response.raise_for_status()
 
    payload = response.json()
    if payload.get("error") is not None or payload.get("statusCode") not in (None, 200):
        raise RuntimeError(payload.get("error", "Shoply API request failed"))
    return payload
 
 
def shoply_post(
    api_name: str,
    payload: dict[str, Any] | None = None,
    **params: Any,
) -> dict[str, Any]:
    """Write store-scoped data and surface HTTP or API-level errors."""
    response = session.post(
        f"{BASE_URL}/{api_name}",
        params={"store_key": STORE_KEY, **params},
        json=payload,
        timeout=60,
    )
    response.raise_for_status()
 
    result = response.json()
    if result.get("error") is not None or result.get("statusCode") not in (None, 200):
        raise RuntimeError(result.get("error", "Shoply API request failed"))
    return result

ตัวอย่างด้านล่างใช้ shared client นี้ โดย helper ทั้งสองตัวจะเพิ่ม authenticated store key ให้อัตโนมัติ

ฉันสามารถจัดการ Shoply AI Knowledge ผ่าน API ได้หรือไม่?

ได้ admin_store_knowledge ใช้ GET เพื่อดึง knowledge และใช้ POST เพื่อสร้าง อัปเดต ลบ หรือ recrawl หาก POST ใช้ knowledge ID ที่มีอยู่แล้ว จะเป็นการอัปเดตรายการนั้น ส่วนการใช้ ID ใหม่จะเป็นการสร้างรายการใหม่

ก่อนทำการอัปเดตแบบอัตโนมัติ ให้วางแผน store knowledge ที่มีประโยชน์ด้วยตัวอย่างในคู่มือการฝึกของเรา

การเขียนข้อมูล knowledge อาจเปลี่ยนคำตอบที่แสดงให้ผู้ซื้อเห็น ควรใช้ secret แยกสำหรับระบบที่จัดการ knowledge ตรวจสอบความถูกต้องของเนื้อหาก่อนส่ง และอย่าเปิดเผยข้อมูลรับรองที่มีสิทธิ์เขียนนี้ใน JavaScript ของ storefront

แสดงรายการ Knowledge ที่มีอยู่

knowledge_payload = shoply_get(
    "admin_store_knowledge",
    knowledge_id_to_retrieve="_ALL_",
)
 
for knowledge_id, knowledge in knowledge_payload["data"].items():
    print(knowledge_id, knowledge.get("title"))

ตัวอย่าง Response

{
  "data": {
    "knowledge::shipping-policy": {
      "title": "Shipping policy",
      "text": "Orders leave our warehouse within two business days.",
      "epoch_edit": 1787211246
    }
  }
}

สร้างหรืออัปเดต Custom Text Knowledge

เลือก knowledge ID ที่คงที่และไม่ซ้ำกัน ใช้ ID เดิมซ้ำเมื่ออัปเดตรายการนั้น

from time import time
 
knowledge_id = "knowledge::shipping-policy"
result = shoply_post(
    "admin_store_knowledge",
    {
        knowledge_id: {
            "title": "Shipping policy",
            "text": (
                "Orders leave our warehouse within two business days. "
                "Standard delivery normally takes three to five business days."
            ),
            "epoch_edit": int(time()),
        }
    },
)
 
print(result)

ตัวอย่าง Response

{
  "statusCode": 200
}

response ที่สำเร็จหมายความว่า knowledge ถูกบันทึกแล้ว การทำดัชนีการค้นหาอาจใช้เวลาหลายนาที ดังนั้นคำตอบใหม่อาจยังไม่แสดงทันที หาก API รายงานว่าเนื้อหาถูกบันทึกแล้วแต่การทำดัชนียังล่าช้า ให้ยืนยันรายการที่เก็บไว้ด้วย GET ก่อนลองเขียนซ้ำ

เพิ่มหน้าเว็บภายนอก

ใช้ ID ที่ขึ้นต้นด้วย external_url:: และใส่ URL แบบเต็ม http:// หรือ https:// ลงใน text

from time import time
 
result = shoply_post(
    "admin_store_knowledge",
    {
        "external_url::returns-policy": {
            "title": "Returns and exchanges",
            "text": "https://www.example.com/policies/returns",
            "epoch_edit": int(time()),
        }
    },
)

อัปโหลดและลงทะเบียนไฟล์ Knowledge

ไฟล์ knowledge ต้องเป็น PDF, TXT หรือ Markdown และมีขนาดเล็กกว่า 5 MB ให้อัปโหลดไฟล์ก่อน แล้วจึงบันทึกตำแหน่ง private S3 ที่ส่งกลับมาเป็นรายการ knowledge

from pathlib import Path
from time import time
 
file_path = Path("shipping-policy.md")
with file_path.open("rb") as file_handle:
    upload_response = session.post(
        f"{BASE_URL}/user_generated_file",
        params={"store_key": STORE_KEY, "folder": "knowledge_file"},
        files={"file": (file_path.name, file_handle, "text/markdown")},
        timeout=60,
    )
 
upload_response.raise_for_status()
uploaded = upload_response.json()
if uploaded.get("statusCode") != 200:
    raise RuntimeError(uploaded.get("error", "Knowledge file upload failed"))
 
shoply_post(
    "admin_store_knowledge",
    {
        "knowledge_file::shipping-policy": {
            "title": "Shipping policy document",
            "text": uploaded["file_url"],
            "epoch_edit": int(time()),
        }
    },
)

ตัวอย่าง Upload Response

{
  "message": "File uploaded successfully",
  "statusCode": 200,
  "file_url": "s3://shoplystores/your-store.myshopify.com/uploads/shipping-policy.md"
}

ให้ถือว่า file_url เป็นตำแหน่งแบบส่วนตัวที่ Shoply ส่งกลับมาโดยตรง อย่าสร้างหรือแก้ไขค่าเอง

ลบ Knowledge

การลบเป็นแบบถาวร ให้ดึงรายการปัจจุบันก่อน และส่งเฉพาะ IDs ที่คุณต้องการลบจริง ๆ เท่านั้น

result = shoply_post(
    "admin_store_knowledge",
    {
        "knowledge_ids_to_delete": [
            "knowledge::shipping-policy",
            "external_url::returns-policy",
            "knowledge_file::shipping-policy",
        ]
    },
)

ขอ Website Recrawl

ใช้ recrawl หลังจากเนื้อหาบนเว็บไซต์ของร้านค้ามีการเปลี่ยนแปลง โดยปกติไม่จำเป็นต้องทำหลังจากอัปเดต custom text ทุกครั้ง

result = shoply_post(
    "admin_store_knowledge",
    re_crawl_ind="true",
)

กรณีใช้งานทางธุรกิจ

• ซิงก์คำแนะนำเกี่ยวกับการจัดส่ง การคืนสินค้า การรับประกัน ไซซ์ หรือการดูแลสินค้า จากระบบจัดการเนื้อหาภายใน
• เผยแพร่ข้อมูลแคมเปญชั่วคราวหรือข้อมูลช่วงวันหยุดโดยไม่ต้องคัดลอกลง Shoply Admin ด้วยตนเอง
• เพิ่มหน้าเว็บนโยบายหรือเอกสารที่ได้รับอนุมัติเข้าสู่ knowledge base เป็นส่วนหนึ่งของเวิร์กโฟลว์ deployment
• ลบคำแนะนำที่ล้าสมัยทันทีเมื่อนโยบายหรือโปรโมชันสิ้นสุดลง

ตัวอย่าง Merchant API

1. ดึงข้อมูลวิเคราะห์ประสิทธิภาพ

admin_store_analytics เป็นเบื้องหลังตาราง Analytics → Summary โดยส่งกลับ sessions, chats, searches, clicks, add-to-cart events, purchases และ attributed revenue

Endpoint

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

Query Parameters

รายงานรายเดือนใช้ประวัติรายเดือนที่ Shoply เก็บไว้และไม่ต้องระบุขอบเขตวันที่

ตัวอย่าง Python

daily_report = shoply_get(
    "admin_store_analytics",
    report_type="daily",
    start_date="20260801",
    end_date="20260820",
)
 
for row in daily_report["data"]:
    print(row["date"], row["sessions"], row["purchases"], row["revenue"])
 
print("Totals:", daily_report["totals"])
 
# Weekly rows use the Monday of each week as their date label.
weekly_report = shoply_get(
    "admin_store_analytics",
    report_type="weekly",
    start_date="20260701",
    end_date="20260820",
)
 
# Monthly requests do not need start_date or end_date.
monthly_report = shoply_get("admin_store_analytics", report_type="monthly")

ตัวอย่าง Response

{
  "data": [
    {
      "date": "20260820",
      "sessions": 42,
      "chats": 18,
      "searches": 24,
      "clicks": 11,
      "add_to_cart": 5,
      "purchases": 2,
      "revenue": "$168.00",
      "revenue_usd": "$168.00"
    }
  ],
  "totals": {
    "date": "totals",
    "sessions": 42,
    "chats": 18,
    "searches": 24,
    "clicks": 11,
    "add_to_cart": 5,
    "purchases": 2,
    "revenue": "$168.00",
    "revenue_usd": "$168.00"
  },
  "report_type": "daily"
}

รายได้อาจมีมากกว่าหนึ่งสกุลเงิน ให้ถือว่า revenue เป็นข้อความสำหรับการแสดงผล ใช้ revenue_usd เมื่อต้องการค่า USD มาตรฐานที่ Shoply แสดง

กรณีใช้งานทางธุรกิจ

• ส่งสรุปผลกระทบต่อยอดขายรายวันให้ร้านค้าหรือทีมอีคอมเมิร์ซ
• เปรียบเทียบ searches, product clicks, add-to-cart events และ purchases เพื่อหาจุดที่ funnel ตกหล่น
• ป้อนข้อมูลเข้าสู่แดชบอร์ด business-intelligence รายสัปดาห์หรือรายเดือนโดยไม่ต้อง scrape หน้า Shoply Admin
• ติดตาม attributed revenue ตามช่วงเวลาและเปรียบเทียบกับการเปลี่ยนแปลงด้าน merchandising หรือแคมเปญ

2. ดึงเขตเวลาของร้านค้า

admin_get_store_metadata ให้ข้อมูล timezone badge ที่แสดงใน Analytics → Chat & Search History โดยหน้านี้ใช้เพื่อแปลงกิจกรรมแบบ UTC เป็นเวลาท้องถิ่นของร้านค้า

Endpoint

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

Query Parameters

ตัวอย่าง Python

timezone_payload = shoply_get(
    "admin_get_store_metadata",
    metadata_key="time_zone",
)
 
timezone = timezone_payload["data"]
print(timezone["ianaTimezone"], timezone["timezoneOffsetMinutes"])

ตัวอย่าง Response

{
  "data": {
    "ianaTimezone": "America/Los_Angeles",
    "timezoneOffset": -7,
    "timezoneOffsetMinutes": -420
  },
  "statusCode": 200
}

กรณีใช้งานทางธุรกิจ

• จัดกลุ่มกิจกรรม UTC ให้ตรงกับวันตามปฏิทินท้องถิ่นเดียวกับที่ร้านค้าเห็นใน Analytics
• ตั้งเวลาการส่งออกประจำวันหลังจากวันท้องถิ่นของร้านค้าสิ้นสุดลงแล้ว
• ติดป้ายกำกับรายงานด้วย IANA timezone ที่ชัดเจน เช่น America/Los_Angeles

offset ของ timezone อาจเปลี่ยนได้เนื่องจากกฎ daylight-saving ควรใช้ ianaTimezone หากระบบรายงานของคุณรองรับ แทนการบันทึก numeric offset แบบถาวรเพียงค่าเดียว

3. ดึงจำนวนกิจกรรม

query_api_usage_count ส่งกลับกิจกรรมของร้านค้าที่จัดกลุ่มตามวันที่ UTC หรือนาที UTC ดั้งเดิม และยังเป็นแหล่งข้อมูลสำหรับ activity chart ใน Analytics → Chat & Search History ด้วย

Endpoint

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

Query Parameters

ตัวอย่าง Python

activity = shoply_get(
    "query_api_usage_count",
    start_dt_utc="2026-08-01 00:00:00",
    end_dt_utc="2026-08-20 23:59:59",
    groupby="utc_date",
)
 
for row in activity["data"]:
    print(row)

ตัวอย่าง Response

{
  "data": [
    {
      "utc_date": "2026-08-20",
      "QA": 18,
      "CHAT": 18,
      "SEARCH": 20,
      "CACHED_SEARCH": 4,
      "PRODUCT_SEARCH": 22,
      "CLICK": 11,
      "ADD_TO_CART": 5,
      "CHECKOUT": 2
    }
  ]
}

แต่ละแถวจะมีตัวนับกิจกรรมที่พร้อมใช้งานสำหรับช่วงเวลานั้น เช่น chat questions, searches, clicks, add-to-cart events และ checkout events ตัวนับที่ไม่มีกิจกรรมอาจไม่ถูกส่งมาเลย แทนที่จะถูกตั้งค่าเป็นศูนย์

กรณีใช้งานทางธุรกิจ

• สร้างกราฟกิจกรรมรายชั่วโมงหรือรายวันเหมือนใน Chat & Search History
• ตรวจจับความผิดปกติ เช่น traffic พุ่งสูงหรือการมีส่วนร่วมของลูกค้าลดลงอย่างรวดเร็ว
• เปรียบเทียบปริมาณ product-search กับ clicks, add-to-cart events และ checkouts
• ประเมินช่วงเวลาที่ทีมซัพพอร์ตและ merchandising ควรตรวจสอบเป็นพิเศษในช่วงที่มีปริมาณสูงสุด

4. ดึงสรุปเซสชันแชตและการค้นหา

query_sessionized_chat ส่งกลับหนึ่งเรกคอร์ดแบบกระชับต่อหนึ่งเซสชันของลูกค้า และยังเป็นเบื้องหลังรายการเซสชันใน Analytics → Chat & Search History

Endpoint

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

Query Parameters

ดึง 40 เซสชันล่าสุด

summary_payload = shoply_get(
    "query_sessionized_chat",
    start_dt_utc="undefined",
    end_dt_utc="undefined",
    num_sessions=40,
    ScanIndexForward="false",
)
 
sessions = summary_payload["data"]
for conversation in sessions:
    print(conversation["customer_id"], conversation.get("user_questions", ""))

ดึงเซสชันในช่วงเวลา UTC

summary_payload = shoply_get(
    "query_sessionized_chat",
    start_dt_utc="2026-08-20 00:00:00",
    end_dt_utc="2026-08-20 23:59:59",
    ScanIndexForward="false",
)

เมื่อมีการระบุขอบเขตเวลาทั้งสองด้าน API จะส่งกลับเซสชันทั้งหมดในช่วงนั้น โดย num_sessions จะไม่จำกัด bounded query นี้

ตัวอย่าง Response

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

ฟิลด์ทางเลือกอาจแตกต่างกันไปในแต่ละเซสชัน ให้เก็บ customer_id, start_timestamp_ms และ end_timestamp_ms ไว้หากคุณวางแผนจะดึงไทม์ไลน์ฉบับสมบูรณ์

กรณีใช้งานทางธุรกิจ

• ตรวจสอบตัวอย่างบทสนทนาล่าสุดเพื่อประเมินคุณภาพคำตอบและฝึกอบรมทีมซัพพอร์ต
• ค้นหาคำถามที่ลูกค้าถามซ้ำ ๆ ซึ่งควรนำไปปรับ product copy หรือ FAQs
• ระบุเซสชันที่มีเจตนาซื้อสูงซึ่งมี searches, product clicks หรือกิจกรรมการซื้อสินค้าอื่น ๆ
• ส่งออกหนึ่งแถวต่อหนึ่งเซสชันเพื่อวิเคราะห์แนวโน้มโดยหลีกเลี่ยง payload ระดับอีเวนต์ที่มีขนาดใหญ่กว่า

5. ดึงเซสชันฉบับสมบูรณ์หนึ่งรายการ

ส่ง summary ที่เลือกไปยัง query_log_visualization เพื่อดึง customer, AI, search และ commerce events ของเซสชันนั้น

Endpoint

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

Query Parameters

ตัวอย่าง Python

from datetime import datetime, timezone
 
 
def utc_from_milliseconds(timestamp_ms: int) -> str:
    """Format a Shoply millisecond timestamp for the history API."""
    value = datetime.fromtimestamp(timestamp_ms / 1000, tz=timezone.utc)
    return value.strftime("%Y-%m-%d %H:%M:%S")
 
 
selected = sessions[0]
timeline_payload = shoply_get(
    "query_log_visualization",
    date_time_utc_start=utc_from_milliseconds(selected["start_timestamp_ms"]),
    date_time_utc_end=utc_from_milliseconds(selected["end_timestamp_ms"]),
    session_id=selected["customer_id"],
    start_timestamp_ms=selected["start_timestamp_ms"],
)
 
for event in timeline_payload["data"]:
    print(event.get("server_timestamp_ms"), event.get("action_type"))

ตัวอย่าง Response

{
  "data": [
    {
      "action_type": "QA",
      "session_id": "customer-or-session-id",
      "utc_date_time": "2026-08-20 00:00:00",
      "start_timestamp_ms": 1787184000000,
      "server_timestamp_ms": 1787184000123,
      "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": {}
    }
  ]
}

ไทม์ไลน์อาจมี customer questions, AI answers, search results, product clicks, add-to-cart events, checkout events และการเข้าร่วมของ human agent ใช้ server_timestamp_ms เพื่อจัดลำดับ event types ที่ปะปนกัน เรคอร์ดรุ่นเก่าอาจมีฟิลด์น้อยกว่า

กรณีใช้งานทางธุรกิจ

• ตรวจสอบอย่างละเอียดว่าลูกค้าถามอะไรและ Shoply ตอบว่าอะไรระหว่างการสืบสวนปัญหาด้านซัพพอร์ต
• ทบทวนคุณภาพคำตอบร่วมกับผลการค้นหาและสินค้าที่แสดงให้ผู้ซื้อเห็น
• สร้างเส้นทางตั้งแต่คำถามไปจนถึง click, add-to-cart หรือ checkout ขึ้นมาใหม่
• วินิจฉัยเซสชันที่ลูกค้ารายงานมาเพียงรายการเดียว โดยไม่ต้องค้นผ่านประวัติที่ไม่เกี่ยวข้อง

ฉันสามารถใช้ Secret เดียวกับทุก API ได้หรือไม่?

ได้ store_owner_api_secrete ที่ถูกต้องจะถูกผูกกับร้านค้าเดียว และใช้งานได้กับ Merchant API endpoints ทั้งหมดข้างต้น สำหรับบัญชี SiteChat secret เดียวกันนี้ยังใช้ยืนยันตัวตนกับ catalog upload APIs ได้ด้วย เพื่อความปลอดภัยในการดำเนินงาน ควรใช้ named secrets แยกตามระบบ เช่น หนึ่งรายการสำหรับการส่งออกข้อมูลตอนกลางคืน และอีกรายการสำหรับแดชบอร์ดภายใน

หากการเชื่อมต่อหนึ่งรายการถูกยกเลิกการใช้งานหรือถูก compromise ให้เพิกถอนเฉพาะ secret ของรายการนั้นใน Shoply Settings ส่วนการเชื่อมต่ออื่นจะยังทำงานต่อไปได้

ฉันควรรู้อะไรเกี่ยวกับวันหมดอายุ ความเป็นส่วนตัว และข้อผิดพลาด?

โปรดอ่านเรื่องแหล่งข้อมูลและความเป็นส่วนตัวของ Shoplyเพิ่มเติม เพื่อทำความเข้าใจว่ามีข้อมูลใดบ้างที่พร้อมให้ใช้ในการตอบคำถามของลูกค้า

• Store-owner API secrets จะหมดอายุหลังจาก 90 วัน สร้างตัวทดแทนและอัปเดตการเชื่อมต่อก่อนถึงวันหมดอายุ
• ระยะเวลาการเก็บประวัติแชตและการค้นหามาตรฐานของ Shoply ก็เป็น 90 วัน เช่นกัน แต่การหมดอายุของ secret และการเก็บข้อมูลเป็นคนละนโยบายกัน
• responses ของประวัติอาจมีข้อมูลส่วนบุคคล รวมถึงตัวระบุลูกค้า อีเมล ตำแหน่งโดยประมาณ คำถาม และกิจกรรมการช้อปปิ้ง ควรจัดเก็บและประมวลผลตามนโยบายความเป็นส่วนตัวของคุณและกฎหมายที่เกี่ยวข้อง
• HTTP 403 หมายความว่า secret หายไป ไม่ถูกต้อง หมดอายุ ถูกเพิกถอน หรือเป็นของร้านค้าอื่น
• HTTP 422 มักหมายความว่า query parameter ที่จำเป็นหายไปหรือใช้ชื่อผิด
• HTTP 500 หรือ response ที่มี statusCode: 500 หมายความว่าคำขอไปถึง Shoply แล้วแต่ไม่สามารถดำเนินการให้เสร็จได้ ให้ retry ความล้มเหลวชั่วคราวด้วย backoff และติดต่อเราหากข้อผิดพลาดยังคงเกิดขึ้นต่อเนื่อง
• ใช้ bounded UTC ranges สำหรับงานส่งออกและงานที่รันซ้ำ เพื่อให้ responses มีขนาดจัดการได้

Product Search เป็นส่วนหนึ่งของ Merchant API หรือไม่?

public product-search API ของ Shoply ใช้รูปแบบการยืนยันตัวตนและ request contract ที่แตกต่างกัน ดู How to Access Shoply AI Search Through the API หากคุณต้องการผลการค้นหาสินค้าสำหรับประสบการณ์ฝั่งผู้ซื้อ แทนข้อมูลส่วนตัวของร้านค้า

ผู้ขาย SiteChat สามารถอัปโหลด Product Catalog ได้หรือไม่?

ได้ บัญชี SiteChat สามารถอัปโหลด structured products และ product images ได้ด้วย store-owner API secret เดียวกัน โดย catalog endpoints เหล่านั้นมีเอกสารแยกไว้ใน How to Upload Your Catalog for SiteChat ส่วนร้านค้า Shopify จะซิงก์สินค้าผ่าน Shopify ต่อไป และไม่ใช้เส้นทางอัปโหลดเหล่านั้น

หากต้องการความช่วยเหลือเกี่ยวกับการเชื่อมต่อ โปรดติดต่อ Shoply AI