Get Conversation

GET

/customer_service/202601/conversations/{conversation_id}

Use this API to retrieve information about a conversation by ID.

Authorizations

• accessToken

Parameters

Path Parameters

conversation_id

required

string

Conversation ID

Query Parameters

shop_cipher

required

string

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

need_session_id

boolean

Set to true to request cur_session_id. The field is returned when current open session information is available; it can also be returned when need_session_info is true.

need_session_info

boolean

Set to true to request cur_session and cur_session_id. These fields are returned when current open session information is available.

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

conversation

Conversation info.

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

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

role

Participant’s role. Possible enumerations:

• BUYER
• SHOP
• CUSTOMER_SERVICE

string

Allowed values: BUYER SHOP CUSTOMER_SERVICE

nickname

Participant’s nickname.

string

avatar

Participant’s avatar URL.

string

user_id

Participant’s ID.

string

platform

Platform the buyer is from. This field is returned only when the participant role is BUYER and the shop region is Indonesia. Possible values:

• TIKTOK_SHOP
• TOKOPEDIA You cannot send platform-specific content to a buyer from another platform. For example, when sending a product card to a Tokopedia buyer, ensure that the product is listed on Tokopedia.

string

Allowed values: TIKTOK_SHOP TOKOPEDIA

create_time

Unix timestamp when the conversation was created. In seconds.

integer format: int64

unread_count

Number of messages unread by the customer service agent.

integer format: int64

cur_session_id

ID of the current open session. This field is returned when need_session_id or need_session_info is true and current open session information is available.

string

cur_session

Information about the current open session. This field is returned when need_session_info is true and current open session information is available.

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": {
    "conversation": {
      "id": "7494560109732334261",
      "participant_count": 3,
      "participants": [
        {
          "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?",
          "user_id": "7494560109732334262",
          "platform": "TIKTOK_SHOP"
        }
      ],
      "create_time": 1691411573,
      "unread_count": 0,
      "cur_session_id": "7494472109882334261",
      "cur_session": {
        "id": "7494472109882334261",
        "phase": "ASSIGNED"
      }
    }
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}