logo
ConsoleSign Up
Document
Client API
Server API
In-app Chat
Overview
Release Notes
Accessing Server APIs
Call API Online
Connect to ZEGOCLOUD Document MCP Serverlink
User
Room
Group
Message
Call invitation
Conversation
Bot
ZIMAudio
Callbacks
Return codes
Debugging guide of server API operations
Privacy policylink
On this page

QueryConversationList

POST

https://zim-api.zego.im/

By calling this API, you can retrieve the complete conversation list of a specified user in pages, returning up to 1000 latest conversations (one-on-one and group chats).

Note
Even if a user is kicked out of a conversation, the API will still return that conversation; however, if the conversation is disbanded, the conversation information cannot be obtained through this API.
QPS Limit
20 times/s

Request

Query Parameters

    Action stringrequired

    Possible values: [QueryConversationList]

    API prototype parameter

    https://zim-api.zego.im/?Action=QueryConversationList

    AppId uint32required

    💡Public parameter. Application ID, assigned by ZEGOCLOUD. Get it from the ZEGOCLOUD Admin Console.

    SignatureNonce stringrequired

    💡Public parameter. A 16-character hexadecimal random string (hex encoding of 8-byte random number). Refer to Signature example for how to generate.

    Timestamp int64required

    💡Public parameter. Current Unix timestamp, in seconds. Refer to Signature example for how to generate, with a maximum error of 10 minutes.

    SignatureVersion stringrequired

    Possible values: [2.0]

    Default value: 2.0

    💡Public parameter. Signature version number.

    Signature stringrequired

    💡Public parameter. Signature, used to verify the legitimacy of the request. Refer to Signing the requests for how to generate an API request signature.

Body

required
    FromUserId stringrequired

    Possible values: <= 32 characters

    Query the conversation list of this UserID (who has logged in to the ZIM service by calling the login method on the client, or has completed registration by calling the server-side API).

    Note

    FromUserId only supports numbers, English characters, and {"'!', '#', '$', '%', '&', '(', ')', '+', '', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', ' ', '{', '}', '|', '~'}.

    Limit number

    Possible values: >= 1 and <= 500

    Default value: 100

    Number of conversations to retrieve at once, default is 100, value range is (0, 500].

    • When the value is ≤ 0, it will be corrected to 100.
    • When the value is > 500, it will be corrected to 500.
    Next number

    Pagination flag. Fill in 0 for the first time, and then fill in the Next value returned from the previous call. When the returned Next is 0, it means the friend list has been fully retrieved.

    For example, if FromUserId has 250 conversations, when calling this API:

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

Responses​

OK
Schema
    Code number

    Return code.

    Return codeDescriptionSuggested Solution
    660000002Input parameter error.Please check the input parameters.
    660300005The API call frequency exceeds the AppID-level limit.Please try again later.
    660500002FromUserId is not registered.Please check if FromUserId is correct.
    660800053Failed to query conversation list.Please contact ZEGOCLOUD Technical Support.
    Message string

    Description of the request result.

    RequestId string

    Request ID.

    TotalCount number

    Total number of current conversations.

    Next number

    Pagination flag.

    • Non-zero: Indicates that there is still conversation information not returned. You need to set this field to the request parameter Next to retrieve more conversation information.
    • Zero: Indicates that the complete conversation list has been returned.

    Note

    Apart from the above description, this field has no association with the list information. Please do not base any other logic on it.

    List object[]
    Conversation list. Results are returned in ascending order by UpdateTime.
  • Array[
    • ConvId string

    Conversation ID.

    • One-on-one conversation: Conversation ID is the peer user's ID.
    • Group conversation: Conversation ID is the group ID.
    ConvType number

    Conversation type.

    • 0 or this field is not returned: One-on-one conversation.
    • 2: Group conversation.
    UpdateTime number

    Last modification time of the conversation, in milliseconds timestamp.

  • ]

Previous

Pin conversations to the top

Next

Query message list from a one-on-one conversation

On this page

Back to top