Get Conversation List

GET

/affiliate_seller/202412/conversations

Retrieve the seller’s IM conversations.

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

Number of conversations to return per page. Range: 1–50.

page_token

string

Pagination cursor. Omit this parameter for the first request. For subsequent pages, use the next_page_token returned by the previous response.

only_need_conversation_id

boolean

• If true, only conversation_id in conversation is returned.
• If false, all fields in conversationare returned.true` by default.

conversation_status

string

Allowed values: ALL UNREAD UNREPLIED STARRED ARCHIVED

Filter the returned IM conversations by status. If omitted, the API returns conversations from all statuses.

Possible values:

• ALL: Retrieve all conversations regardless of status.
• UNREAD: Retrieve conversations with messages the seller has not read. Messages remain unread until explicitly marked as read by calling Mark Conversation Read; replying does not change the read status.
• UNREPLIED: Retrieve conversations in which the seller is not the last message sender.
• STARRED: Retrieve conversations the seller starred.
• ARCHIVED: Retrieve conversations the seller archived.

Request Body

Media typeapplication/json

object

only_need_conversation_id

• If true, only conversation_id in data.conversation is returned.
• If false, all fields in data.conversation are returned. true by default.

boolean

Example^generated

{
  "only_need_conversation_id": true
}

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

has_more

Whether there are more conversations.

boolean

next_page_token

Pagination cursor for the next page. When has_more is true, pass this value as page_token in the next request.

string

conversations

The conversation list.

Array<object>

object

id

Conversation unique ID.

string

unread_count

Number of unread messages.

integer format: int64

username

The TikTok user name.

string

avatar

The URL for the TikTok creator’s avatar image file.

string

creator_im_id

Creators’ IM User ID.

string

Example

{
  "code": 0,
  "data": {
    "has_more": true,
    "next_page_token": "12345678",
    "conversations": [
      {
        "id": "12345678",
        "unread_count": 2,
        "username": "test_creator_name",
        "avatar": "https://p16-sign-useast2a.tiktokcdn.com/tos-useast2a-avt-0068-giso/2bf6a2485ec8bf93483e4a6ed907e6fd~c5_720x720.webp",
        "creator_im_id": "12345678"
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}