Skip to content
TikTok Shop Partner API

Get Conversation Messages

GET
/customer_service/202309/conversations/{conversation_id}/messages

Use this API to retrieve a page of messages in a conversation between a buyer and a shop. Calling this API does not mark messages as read. Call Read Message to mark them as read.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
conversation_id
required
string

Conversation ID

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 messages to return per page. The value must be between 1 and 10, inclusive.

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)
sort_order
string
Allowed values: DESC ASC

Sort order. Possible enumerations:

  • DESC(default)
  • ASC
sort_field
string

Sort messages by one of the following properties:

  • create_time (default)
  • index
need_data
boolean

Whether to request the data field for visible messages when structured data is available. Default: false.

need_plaintext
boolean

Whether to request the plaintext field for visible messages when a human-readable representation is available. Default: false.

time_zone
string

Time zone used to format date and time values in supported message content, including generated plaintext. This parameter does not change create_time, which remains a Unix timestamp in seconds. Use an IANA time zone name, such as Asia/Shanghai or America/Los_Angeles. Default: UTC.

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
unsupported_msg_tips

If your app encounters a message type it doesn’t support, you can display the text to guide the user to check the message in TikTok Shop. The content of the message depends on the specific locale.

string
messages

Messages in conversation.

Array<object>
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
  • LOGISTICS_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 LOGISTICS_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"
}
  • LOGISTICS_CARD:
{
    "order_id": "12345",
    "package_id": "321"
}
  • 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

The message sender. For system and robot roles, shop is the sender.

object
im_user_id

Sender’s ID. These are IM IDs, and can not be used to query orders.

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
avatar

Sender’s avatar URL.

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
data

Structured message data encoded as a JSON string. Request it with need_data=true. The field is available only for visible messages and message types for which structured data can be generated.

For a LOGISTICS_CARD message, predict_delivery_time_min, predict_delivery_time_max, and tracking[].update_time_millis are Unix timestamps in milliseconds and remain raw numeric values in data. The time_zone request parameter affects the generated localized plaintext; it does not convert these structured-data timestamp values.

Example for a LOGISTICS_CARD message:

{
  "packages": [
    {
      "package_id": "456",
      "product_name": "Nutrition",
      "product_image": "https://cdn-us.com/us/123jpeg:1000:1000.jpeg?dr=123&t=555",
      "paid_price": "$0.01",
      "quantity": 1,
      "predict_delivery_time_min": 1763198750000,
      "predict_delivery_time_max": 1763457950000,
      "delivery_option": "Standard shipping",
      "tracking_number": "1Z789",
      "shipping_provider_name": "UPS",
      "tracking": [
        {
          "description": "Package has been delivered!",
          "update_time_millis": 1763954669267
        },
        {
          "description": "Arrived at the carrier's facility.",
          "update_time_millis": 1763954598311
        },
        {
          "description": "Package picked up.",
          "update_time_millis": 1763954598024
        },
        {
          "description": "Order packed and ready for dropoff at carrier's facility.",
          "update_time_millis": 1763451813897
        },
        {
          "description": "Order placed.",
          "update_time_millis": 1763112346906
        }
      ]
    }
  ]
}
string
plaintext

Human-readable message content. Request it with need_plaintext=true. The field is available only for visible messages and message types for which plaintext can be generated.

Example for a PRODUCT_CARD message: Product card shared:

  • Product ID: 1732529206731441911;
  • Product name: Áo Khoác Cardigan Logo Thêu Phong Cách Hàn Quốc By Zonef, Áo Khoác Thu Đông Chất Vải Cotton Tổ Ong Nam Nữ Unisex;
  • Product price: ;
  • Strike-through price:
  • Sold: 40013.

View full details at: https://seller-vn.tiktok.com/product/manage?search_content=1732529206731441911

string
Example
{
  "code": 0,
  "data": {
    "next_page_token": "162312320",
    "unsupported_msg_tips": "Please check this message in Seller Center.\n",
    "messages": [
      {
        "id": "7494560109732334263",
        "type": "TEXT",
        "content": "{\"content\": \"simple text message\"}",
        "create_time": 1691411573,
        "is_visible": true,
        "sender": {
          "im_user_id": "7494560109732334261",
          "role": "BUYER",
          "nickname": "Albert",
          "avatar": "https://p16-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/566c497faaaf4491a84d3ce55d9cb095~tplv-omjb5zjo8w-origin-image.image?"
        },
        "index": "7494560109732334274",
        "data": "{}",
        "plaintext": "Product card shared:\n- Product ID: 1732529206731441911; \n- Product name: Áo Khoác Cardigan Logo Thêu Phong Cách Hàn Quốc By Zonef, Áo Khoác Thu Đông Chất Vải Cotton Tổ Ong Nam Nữ Unisex; \n- Product price: ; \n- Strike-through price: \n- Sold: 40013. \n\nView full details at: https://seller-vn.tiktok.com/product/manage?search_content=1732529206731441911"
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec