Skip to content
TikTok Shop Partner API

Get Conversations

GET
/customer_service/202309/conversations

Use this API to retrieve a shop’s conversations with buyers.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
shop_cipher
required
string

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

page_token
string

Paging cursor, this means where this query should start. For the next page, use “next_page_token” in response.

page_size
required
integer format: int64

Number of conversations to return per page. Must be between 1 and 20.

locale
string
Allowed values: de-DE en en-GB es-ES es-MX fr-FR id-ID it-IT ja-JP ms-MY th-TH vi-VN pt-BR zh-CN

System message’s display language. The messages sent by System will be returned in the setting language; The messages sent by the buyer, the shop, the CS agent will not be affected. The default value is en (English).

Possible enumerations:

  • de-DE (German, Germany)
  • en (English)
  • en-GB (English, United Kingdom)
  • es-ES (Spanish, Spain)
  • es-MX (Spanish, Latin America)
  • fr-FR (French, France)
  • id-ID (Indonesian, Indonesia)
  • it-IT (Italian, Italy)
  • ja-JP (Japanese)
  • ms-MY (Malay, Malaysia)
  • th-TH (Thai, Thailand)
  • vi-VN (Vietnamese, Vietnam)
  • pt-BR (Portuguese, Brazil)
  • zh-CN (Simplified Chinese, China)
need_session_id
boolean

Set to true to request cur_session_id. The field is returned only when the conversation has a current open session whose public phase is AUTO_REPLY, QUEUED, or ASSIGNED. Setting need_session_info to true also requests this field.

need_session_info
boolean

Set to true to request cur_session and cur_session_id. These fields are returned only when the conversation has a current open session whose public phase is AUTO_REPLY, QUEUED, or ASSIGNED.

Responses

Section titled “Responses”

200

Section titled “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

The index indicates where we should start on the next page. If there is no more record, this field will be “”(empty string). Put this value to request param “page_token” for the next page query.

string
conversations

Conversation info.

Array<object>
object
id

Conversation ID

string
participant_count

Number of participants in the conversation.

  • If there has been no customer service agent in the conversation, the value is 2: the shop and the buyer;
  • Otherwise, the value is 3: the shop, the buyer, and the customer service agent.
integer format: int64
can_send_message

Whether customer service agent can send message in this conversation. Under any of the following circumstances, the CS agent can send messages:

  1. There has been a prior conversation between the buyer and the shop within the last 30 days.
  2. The buyer placed an order at the shop within the past 60 days.
  3. The buyer has a history of returns or refunds at the shop.
boolean
unread_count

Number of messages unread by the customer service agent.

integer format: int64
create_time

Unix timestamp when the conversation was created. In seconds.

integer format: int64
participants

Conversation participants.

Array<object>
object
im_user_id

Participant’s ID, in IM system. This ID is used in IM system and can not be used to query orders. To query orders, use user_id instead.

string
avatar

Participant’s avatar URL.

string
user_id

Participant’s ID.

string
role

Participant’s role. Possible enumerations:

  • BUYER
  • SHOP
  • CUSTOMER_SERVICE
string
Allowed values: BUYER SHOP CUSTOMER_SERVICE
nickname

Participant’s nickname.

string
buyer_platform

Which platform is the buyer from. This field will only be returned when the participant’s role is BUYER and the shop’s region is Indonesia. Possible enumerations:

  • TIKTOK_SHOP
  • TOKOPEDIA You cannot send platform-specific content to the buyer from a different platform. For example, when you send a product card to the Tokopedia buyer, you must ensure the product is listed on Tokopedia.
string
Allowed values: TIKTOK_SHOP TOKOPEDIA
latest_message

The latest message in conversation.

object
id

Message ID.

string
type

Message type. Possible enumerations:

  • TEXT
  • IMAGE
  • ALLOCATED_SERVICE - A customer service agent joins the conversation.
  • NOTIFICATION - Notification from the system.
  • BUYER_ENTER_FROM_TRANSFER : The conversation is transferred to another customer service agent.
  • BUYER_ENTER_FROM_PRODUCT : The buyer is viewing a product before sending this message.
  • BUYER_ENTER_FROM_ORDER : The buyer is viewing an order before sending this message.
  • PRODUCT_CARD
  • EMOTICONS
  • ORDER_CARD
  • VIDEO
  • RETURN_REFUND_CARD: Return/refund card.
  • COUPON_CARD
  • OTHER: Messages of types not supported in this API.
string
Allowed values: TEXT IMAGE ALLOCATED_SERVICE NOTIFICATION BUYER_ENTER_FROM_TRANSFER BUYER_ENTER_FROM_PRODUCT BUYER_ENTER_FROM_ORDER PRODUCT_CARD EMOTICONS ORDER_CARD VIDEO RETURN_REFUND_CARD COUPON_CARD OTHER
content

Message content, in JSON serialized string. Examples of content for each type of message are listed below:

  • TEXT:
{
    "content": "simple text"
}
  • IMAGE:
{
    "height": "290",
    "url": "https://tosv.boei18n.byted.org/obj/temai-im/FszkJ53nSapYG6KDaJQmqR3jjoZGwww304-290",
    "width": "304"
}
  • PRODUCT_CARD, BUYER_ENTER_FROM_PRODUCT:
{
    "product_id": "12345"
}
  • ORDER_CARD, BUYER_ENTER_FROM_ORDER :
{
    "order_id": "12345"
}
  • RETURN_REFUND_CARD:
{
    "order_id": "12345",
    "sku_id": "45678"
}
  • VIDEO:
{
    "url": "https://video-boei18n.byted.org/storage/v1/tos-boei18n-v-c72c01/e8240f35244646428df9c3244d1a7408?x-tos-algorithm=v2&x-tos-authkey=5bf25627da095a5cba28ace592de46cc&x-tos-expires=1681980481&x-tos-signature=r_bRxtrvGhXAuZgMmNhlZ_Upqzg",
    "cover": "https://p-boei18n.byted.org/tos-boei18n-v-c72c01/o8keEOhzTcNCcJyAbkWZwpLIyTfkJxcGbRBvLP~tplv-jvtte31kaf-origin-jpeg.jpeg?",
    "width": 640,
    "height": 360,
    "duration": "20.504",
    "vid": "v0e30cg700f7cgcmu8jc77u9e2bdp95g",
    "expire_time": "1681980481",
    "format": "mp4",
    "size": 400000,
    "bit_rate": 156067,
    "quality": "original",
    "codec_type": "h264"
}
  • ALLOCATED_SERVICE, NOTIFICATION, BUYER_ENTER_FROM_TRANSFER, OTHER:
{
    "content": "simple text"
}
  • COUPON_CARD:
{
    "coupon_id": "7262992004278206762"
}

Note: Use Get Coupon for the details of the coupon.

string
create_time

Unix timestamp for creating the message in seconds.

integer format: int64
is_visible

Whether this message should be displayed to customer service. For example, the buyer will receive a rating request message at the end of the conversation from the system. You should not present this type of message to the seller or the customer support agents.

boolean
sender

Sender of the message.

object
im_user_id

Sender’s IM ID. Sender’s unique identifier in TikTok Shop’s IM system.

string
avatar

Sender’s avatar URL.

string
role

Sender’s role. Possible enumerations:

  • BUYER
  • SHOP
  • CUSTOMER_SERVICE
  • SYSTEM
  • ROBOT For SYSTEM and ROBOT role, the value of im_user_id, nickname, and avatar are the same as those of the SHOP role.
string
Allowed values: BUYER SHOP CUSTOMER_SERVICE SYSTEM ROBOT
nickname

Sender’s nickname.

  • For shops, the nickname is the shop’s name.
  • For customer service, the nickname is the customer service’s name.
  • For buyers, the nickname is the buyer’s nickname on TikTok. You can set the nicknames for shops and customer service agents on Seller Center.
string
index

Message index. This field can be used to sort messages. “index” means the order of the message in the conversation. This value is unique for every message in a conversation. This value is time-related, meaning a newer message will get a larger “index”. But it is not strictly increasing.

string
cur_session_id

Current session id.

string
cur_session

Current session.

object
id

Current session id.

string
phase

Current phase of the session. Possible enumerations:

  • AUTO_REPLY — The session is being handled by automatic replies or chatbot responses.
  • QUEUED — The session is waiting to be assigned to an agent.
  • ASSIGNED — The session has been assigned to an agent.
string
Allowed values: AUTO_REPLY QUEUED ASSIGNED
Example
{
  "code": 0,
  "data": {
    "next_page_token": "1612353423",
    "conversations": [
      {
        "id": "7494560109732334261",
        "participant_count": 3,
        "can_send_message": true,
        "unread_count": 0,
        "create_time": 1691411573,
        "participants": [
          {
            "im_user_id": "7494560109732334261",
            "avatar": "https://p16-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/566c497faaaf4491a84d3ce55d9cb095~tplv-omjb5zjo8w-origin-image.image?",
            "user_id": "7494560109732334262",
            "role": "BUYER",
            "nickname": "Albert",
            "buyer_platform": "TIKTOK_SHOP"
          }
        ],
        "latest_message": {
          "id": "7494560109732334263",
          "type": "TEXT",
          "content": "{\"content\": \"simple text message\"}",
          "create_time": 1691411573,
          "is_visible": true,
          "sender": {
            "im_user_id": "7494560109732334261",
            "avatar": "https://p16-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/566c497faaaf4491a84d3ce55d9cb095~tplv-omjb5zjo8w-origin-image.image?",
            "role": "BUYER",
            "nickname": "Albert"
          },
          "index": "7494560109732334274"
        },
        "cur_session_id": "7494472109882334261",
        "cur_session": {
          "id": "7494472109882334261",
          "phase": "ASSIGNED"
        }
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec