Query conversation list

Overview

You can call this operation to paginate and fetch the all conversation list. It can return up to 1000 latest conversations, including both one-on-one and group chats.

Note

Even if the user is kicked out of the conversation, the result returned by this interface still includes the conversation. However, if the conversation is dissolved, it is not possible to obtain relevant information about the conversation through this interface.

Operation prototype

Request method: POST
Request URL: https://zim-api.zego.im/?Action=QueryConversationList
Protocol: HTTPS
QPS limit: 20 calls per second.

Request parameters

The following table describes only the operation-specific request parameters and some common request parameters. For the complete list of common request parameters, see the Public request parameters section of the Accessing Server APIs topic.

Parameter	Type	Required	Description
FromUserId	String	Yes	Query the conversation list for this registered UserID.
Limit	Number	No	Number of conversations to retrieve in one request. The default is 100, with a range of (0, 500]. If the value is ≤ 0, it will be adjusted to 100. If the value is > 500, it will be adjusted to 500.
Next	Number	No	Paging flag for fetching data. Set to 0 for the first request and then set it to the Next value returned from the previous request. When the returned Next value is 0, it means that the conversation list retrieval is complete. For example, if there are 250 conversations for FromUserID, and you call this interface to query: First call to this interface, set Limit to 100 and Next to 0, to query conversations 1-100; the Next value in the returned result is num1. Second call to this interface, set Limit to 100 and Next to num1, to query conversations 101-200; the Next value in the returned result is num2. Third call to this interface, set Limit to 100 and Next to num2, to query conversations 201-250; the query is complete, and the Next value in the returned result is 0.

Parameter

Type

Required

Description

FromUserId

String

Yes

Query the conversation list for this registered UserID.

Limit

Number

Number of conversations to retrieve in one request. The default is 100, with a range of (0, 500].

If the value is ≤ 0, it will be adjusted to 100.
If the value is > 500, it will be adjusted to 500.

Number

Paging flag for fetching data. Set to 0 for the first request and then set it to the Next value returned from the previous request. When the returned Next value is 0, it means that the conversation list retrieval is complete.

For example, if there are 250 conversations for FromUserID, and you call this interface to query:

First call to this interface, set Limit to 100 and Next to 0, to query conversations 1-100; the Next value in the returned result is num1.
Second call to this interface, set Limit to 100 and Next to num1, to query conversations 101-200; the Next value in the returned result is num2.
Third call to this interface, set Limit to 100 and Next to num2, to query conversations 201-250; the query is complete, and the Next value in the returned result is 0.

Note

The FromUserId parameter can contain only digits, letters, and the following characters: '!'，'#'，'$'，'%'，'&'，'('，')'，'+'，'-'，':'，';'，'<'，'='，'.'，'>'，'?'，'@'，'['，']'，'^'，'_'，' '，'{'，'}'，'|'，'~'.

Sample request

Request URL：

Untitled

https://zim-api.zego.im/?Action=QueryConversationLit
    &<Common request parameters>

Copied!

Request message body:

Untitled

 {
     "FromUserId": "u1",
     "Limit": 10,
     "Next": 0
}

Copied!

Response parameters

Parameter	Type	Description
Code	Number	The return code.
Message	String	The description of the request result.
RequestId	String	The request ID.
TotalCount	Number	The total number of current conversations.
Next	Number	Pagination flag. Not 0: indicates that there is more conversation information to be returned, and this field needs to be set to the Next parameter in the request to fetch more conversation information. 0: indicates that the complete conversation list has been returned.
List	Array of Object	Conversation list. Return the results in ascending order based on UpdateTime.
└ConvId	String	Conversation ID. One-to-one chats: The conversation ID is the ID of the other user. Group chats: The conversation ID is the group ID.
└ConvType	Number	The conversation type. 0 or this field is not returned: One-to-one chats. 2: Group chats.
└UpdateTime	Number	Last modified time of the conversation, in milliseconds timestamp.

Sample response

Untitled

{
    "Code": 0,
    "Message": "success",
    "RequestId": "343649807833778782",
    "TotalCount": 500,
    "Next": 1000,
    "List": [
        {
            "ConvId": "conv1",
            "ConvType": 2,
            "UpdateTime": 1708254395000
        },
        {
            "ConvId": "conv2",
            "ConvType": 0,
            "UpdateTime": 1708254395000
        },
        {
            "ConvId": "conv3",
            "UpdateTime": 1708254395000
        }
    ]
}

Copied!

Return codes

The following table describes only the return codes related to the business logic of the operation. For the complete list of return codes, see Return codes.

Return Code	Description	Solution
660000002	Invalid parameter.	Check the input parameter.
660300005	The QPS limit specified in `AppID` is exceeded.	Try again later.
660500002	`FromUserId` is not registered.	Check if `FromUserId` is correct.
660800053	Failed to query conversation list.	Contact ZEGOCLOUD technical support.