Search Sessions

POST

/customer_service/202602/sessions/search

Search customer service sessions by their start-time range and, optionally, the buyer’s nickname.

Authorizations

• accessToken

Parameters

Query Parameters

shop_cipher

required

string

Identifies the shop. Obtain it from the Get Authorized Shops API.

page_size

required

integer format: int64

>= 1 <= 100

The number of results to be returned per page. Valid range: [1-100]

page_token

string

An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the next_page_token from a previous response. It is not needed for the first page.

locale

string

The BCP-47 locale codes for displaying the rejection reason, delimited by commas. Default: en-US Refer to https://partner.tiktokshop.com/docv2/page/678e3a47bae28f030a8c7523 for the list of supported locale codes.

Request Body^required

Media typeapplication/json

object

begin_time_ge

required

Return sessions whose begin_time is greater than or equal to this Unix timestamp, in seconds. Only data from the last 90 days is supported.

integer format: int64

begin_time_lt

required

Return sessions whose begin_time is less than this Unix timestamp, in seconds. The value must be greater than or equal to begin_time_ge.

integer format: int64

buyer_nickname

Filter sessions by the buyer’s nickname.

string

Example

{
  "begin_time_ge": 1773222516,
  "begin_time_lt": 1773242516,
  "buyer_nickname": "Albert"
}

Responses

200

Success

Media typeapplication/json

object

code

Status code; 0 means success.

integer format: int64

message

Success or failure message.

string

request_id

Request log ID.

string

data

object

next_page_token

If there is no more record, this field will be “”(empty string).

string

sessions

Customer service sessions that match the request filters.

Array<object>

object

id

Session id.

string

conversation_id

Conversation id.

string

begin_time

The Unix timestamp, in seconds, when the session began.

integer format: int64

end_time

The timestamp when the session end.

integer format: int64

buyer_nickname

Buyer’s nickname.

string

chat_tags

AfterSale/Logistics/Presale

Array<string>

satisfaction_score

Customer satisfaction rating for the session (e.g., 1–5). Higher scores indicate greater satisfaction.

integer format: int64

dissatisfaction_reason

Reason provided by the buyer for a low satisfaction rating. The language of the reason is determined by the locale request parameter.

string

first_response_late

Indicates whether the first response exceeded the expected response time or SLA.

boolean

first_response_time

Time elapsed in seconds between when the buyer sends the first message and when the seller sends the first response.

integer format: int64

Example

{
  "code": 0,
  "data": {
    "next_page_token": "10",
    "sessions": [
      {
        "id": "7494560109732334261",
        "conversation_id": "7601726193700929800",
        "begin_time": 1773222516,
        "end_time": 1773232516,
        "buyer_nickname": "Albert",
        "chat_tags": [
          "Logistics"
        ],
        "satisfaction_score": 4,
        "dissatisfaction_reason": "Slow response or resolution",
        "first_response_late": false,
        "first_response_time": 123
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}