Get Conversations

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

---

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) | need_session_id |bool |N |false |Set to true when session id is required. | need_session_info |bool |N |false |Set to true when session info is required. |

Query

https://open-api.tiktokglobalshop.com/customer_service/202309/conversations?app_key=123abc&sign=5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c&timestamp=1625484268&shop_cipher=ROW_RHkDDABBAAB8tKAVoAqsMTjsQZFLyNfY&page_token=1612356123&page_size=10&locale=en&need_session_id=false&need_session_info=false

• 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. | ^^can_send_message |bool |true |Whether customer service agent can send message in this conversation. Under any of the following circumstances, the CS agent can send messages:
• There has been a prior conversation between the buyer and the shop within the last 30 days.
• The buyer placed an order at the shop within the past 60 days.
• The buyer has a history of returns or refunds at the shop. | ^^unread_count |int |0 |Number of messages unread by the customer service agent. | ^^create_time |int |1691411573 |Unix timestamp when the conversation was created. In seconds. | ^^participants |[]object | |Conversation participants. | ^^^im_user_id |string |7494560109732334261 |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. | ^^^avatar |string |https://p16-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/566c497faaaf4491a84d3ce55d9cb095~tplv-omjb5zjo8w-origin-image.image? |Participant's avatar URL. | ^^^user_id |string |7494560109732334262 |Participant's ID. | ^^^role |string |BUYER |Participant's role. Possible enumerations:
• BUYER
• SHOP
• CUSTOMER_SERVICE | ^^^nickname |string |Albert |Participant's nickname. | ^^^buyer_platform |string |TIKTOK_SHOP |Which platform is the buyer from. This field will only be returned when the role is BUYER and the 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. | ^^latest_message |object | |The latest message in conversation. | ^^^id |string |7494560109732334263 |Message ID. | ^^^type |string |TEXT |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. | ^^^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"
}

• 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 | |Sender of the message. | ^^^^im_user_id |string |7494560109732334261 |Sender's IM ID. Sender's unique identifier in TikTok Shop's IM system. | ^^^^avatar |string |https://p16-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/566c497faaaf4491a84d3ce55d9cb095~tplv-omjb5zjo8w-origin-image.image? |Sender's avatar URL. | ^^^^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. | ^^^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. | ^^cur_session_id |string |7494472109882334261 |Current session id. | ^^cur_session |object | |Current session. | ^^^id |string |7494472109882334261 |Current session id. | ^^^phase |string |ASSIGNED |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. |

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

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