• 简体中文

      • 会话 API

      会话 API 用来读取当前店铺的会话。调用前需要先完成开放平台鉴权。

      基础路径：

      /open/v1/conversations

      目前可以列出会话，以及获取单条会话和其中的消息。这些请求都是只读的，不会把会话标记为已读。

      会话字段

      字段类型说明
      idstring会话 ID。
      createdAtstring 或 null创建时间，UTC。
      closedAtstring 或 null关闭时间，UTC。会话仍未关闭时为 null。
      lastMessageAtstring 或 null最后一条消息的时间，UTC。尚未记录消息时间时为 null。
      firstTextstring 或 null第一条消息文本。
      lastMessageTextstring 或 null最后一条消息文本，截断到 100 个字符。
      customerNamestring 或 null客户名称。
      sourcePagestring 或 null会话开始时所在页面的 URL。
      sourceTitlestring 或 null该页面的标题。
      tagsarray会话标签。没有标签时为空数组。
      readboolean店铺是否已读该会话。
      botRepliedboolean机器人是否已回复。
      hasBotboolean是否有机器人参与。
      archivedboolean会话是否已归档。
      emailstring 或 null客户邮箱。
      phonestring 或 null客户电话。
      ratingnumber 或 null客户评分。客户未评分时为 null。
      ratingMessagestring 或 null评分时留下的评论。
      userAgentstring 或 null会话开始时记录的浏览器 User-Agent。

      消息字段

      只在获取单条会话时返回。

      字段类型说明
      idstring消息 ID。
      typestringtext 或 frame-html。
      textstring 或 null消息文本。frame-html 时，这里是 HTML 内容。
      createdAtstring 或 null创建时间，UTC。
      senderNamestring 或 null发送方显示名称。
      senderTypestringcustomer 或 shop。

      列出会话

      POST /open/v1/conversations/search
Content-Type: application/json

      请求体可选。空对象 {} 会按创建时间排序，返回默认分页大小的第一页。

      请求体：

      字段必填默认值说明
      page否1页码，从 1 开始。
      pageSize否20每页数量，最大 50。
      orderBy否newestnewest 按创建时间排序。lastMessage 按最后一条消息排序。
      createdFrom否无包含该时间及之后创建的会话。例如 2026-09-01T00:00:00Z。
      createdTo否无包含该时间及之前创建的会话。例如 2026-09-30T23:59:59Z。
      lastMessageFrom否无包含最后一条消息在该时间及之后的会话。例如 2026-09-01T00:00:00Z。
      lastMessageTo否无包含最后一条消息在该时间及之前的会话。例如 2026-09-30T23:59:59Z。
      read否无true 或 false。
      archived否无true 或 false。
      hasBot否无true 或 false。
      botReplied否无true 或 false。
      closed否无true 或 false。
      email否无精确匹配客户邮箱。例如 ada@example.com。
      tags否无每个标签都必须匹配。例如 ["order", "vip"]。

      createdFrom、createdTo、lastMessageFrom 和 lastMessageTo 使用同一种 UTC ISO-8601 格式：YYYY-MM-DDTHH:mm:ssZ。带时区偏移的时间也可以，例如 2026-09-01T08:00:00+08:00。不要只传日期，例如 2026-09-01，也不要传毫秒时间戳。

      page 必须大于等于 1。pageSize 必须在 1 到 50 之间。orderBy 只能是 newest 或 lastMessage。开始时间不能晚于结束时间。JSON 格式错误也会返回 400。

      {
  "page": 1,
  "pageSize": 20,
  "orderBy": "lastMessage",
  "createdFrom": "2026-09-01T00:00:00Z",
  "createdTo": "2026-09-30T23:59:59Z",
  "archived": false,
  "closed": false,
  "botReplied": true,
  "email": "ada@example.com",
  "tags": ["order", "vip"]
}

      200 响应：

      {
  "items": [
    {
      "id": "support-group-665f0c2e0f1a2b3c4d5e6f70",
      "createdAt": "2026-09-04T00:00:00Z",
      "closedAt": null,
      "lastMessageAt": "2026-09-04T00:05:00Z",
      "firstText": "Where is my order?",
      "lastMessageText": "It ships tomorrow.",
      "customerName": "Ada",
      "sourcePage": "https://example.myshopify.com/products/tote",
      "sourceTitle": "Tote",
      "tags": ["order"],
      "read": false,
      "botReplied": true,
      "hasBot": true,
      "archived": false,
      "email": "ada@example.com",
      "phone": null,
      "rating": null,
      "ratingMessage": null,
      "userAgent": "Mozilla/5.0"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1
}

      没有匹配结果时仍然返回 200，此时 items 为 []，total 为 0。

      获取单条会话

      GET /open/v1/conversations/{id}

      路径参数：

      参数说明
      id会话 ID。

      200 响应：

      {
  "id": "support-group-665f0c2e0f1a2b3c4d5e6f70",
  "createdAt": "2026-09-04T00:00:00Z",
  "closedAt": null,
  "lastMessageAt": "2026-09-04T00:05:00Z",
  "firstText": "Where is my order?",
  "lastMessageText": "It ships tomorrow.",
  "customerName": "Ada",
  "sourcePage": "https://example.myshopify.com/products/tote",
  "sourceTitle": "Tote",
  "tags": ["order"],
  "read": false,
  "botReplied": true,
  "hasBot": true,
  "archived": false,
  "email": "ada@example.com",
  "phone": null,
  "rating": null,
  "ratingMessage": null,
  "userAgent": "Mozilla/5.0",
  "messages": [
    {
      "id": "665f0c2e0f1a2b3c4d5e6f71",
      "type": "text",
      "text": "Where is my order?",
      "createdAt": "2026-09-04T00:00:00Z",
      "senderName": "Ada",
      "senderType": "customer"
    },
    {
      "id": "665f0c2e0f1a2b3c4d5e6f72",
      "type": "text",
      "text": "It ships tomorrow.",
      "createdAt": "2026-09-04T00:05:00Z",
      "senderName": "Shop",
      "senderType": "shop"
    }
  ]
}

      messages 按时间从旧到新排列。会话没有消息时为 []。

      如果这个 ID 在当前已鉴权店铺中不存在，返回 404。