Get Conversation Messages

Use this API to get all messages in a conversation between a buyer and a shop. Calling this API does not mark the messages as read. You are suggested to call Read Message to mark the messages read.

---

For common parameters, refer to How to call TikTok Shop APIs - Common Parameters

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 |N |DESC |Sort order. Possible enumerations:
• DESC(default)
• ASC | sort_field |string |N |create_time |Sort messages by one of the following properties:
• create_time (default)
• index | need_data |bool |N |false |Need message.data | need_plaintext |bool |N |false |Need message.plaintext | time_zone |string |N |Asia/Shanghai |Time zone for formatting date and time in messages. The timestamps in messages will be returned in the specified time zone; other message content will not be affected.

The value must follow the IANA time zone format (for example, Asia/Shanghai, America/Los_Angeles). The default value is UTC. |

Query

https://open-api.tiktokglobalshop.com/customer_service/202309/conversations/7494560109732334261/messages?app_key=123abc&sign=5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c&timestamp=1625484268&shop_cipher=ROW_RHkDDABBAAB8tKAVoAqsMTjsQZFLyNfY&page_token=7494560109732337542&page_size=10&locale=en&sort_order=DESC&sort_field=create_time&need_data=false&need_plaintext=false&time_zone=Asia/Shanghai

• 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. | ^^content |string |{"content": "simple text message"} |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. | ^^create_time |int |1691411573 |Unix timestamp for creating the message in seconds. | ^^is_visible |bool |true |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. | ^^sender |object | |The message sender. For system and robot roles, shop is the sender. | ^^^im_user_id |string |7494560109732334261 |Sender's ID. These are IM IDs, and can not be used to query orders. | ^^^role |string |BUYER |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. | ^^^nickname |string |Albert |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. | ^^^avatar |string |https://p16-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/566c497faaaf4491a84d3ce55d9cb095~tplv-omjb5zjo8w-origin-image.image? |Sender's avatar URL. | ^^index |string |7494560109732334274 |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. | ^^data |string |{} |{ "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 } ] } ] } | ^^plaintext |string |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 |- PRODUCT_CARD 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 |

{"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"}

For common error codes, refer to How to call TikTok Shop APIs - Common Error Code