Query the friend list

Overview

You can call this operation to query the list of friends by page based on user IDs, including information such as the friend alias and friendship creation time.

Operation prototype

Request method: GET
Request URL: https://zim-api.zego.im/?Action=QueryFriendList
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 The ID of the registered user whose friend list is to be queried.

Limit Number Yes The number of friends to be pulled per time. Value range: [0, 100]. If this parameter is not specified, is set to 0, or is greater than 100, the value 100 is used.

Number

Yes

Parameter	Type	Required	Description
FromUserId	String	Yes	The ID of the registered user whose friend list is to be queried.
Limit	Number	Yes	The number of friends to be pulled per time. Value range: [0, 100]. If this parameter is not specified, is set to `0`, or is greater than 100, the value `100` is used.
Next	Number	Yes	The flag for a paginated pull. For the first pull, set this parameter to `0`. For subsequent pulls, enter the value returned from the previous pull. If `Next` is `0` in the returned result, the list of all friends is obtained. For example, if `FromUserId` has 250 friends: In the first call, set `Limit` to `100` and `Next` to `0` to query the first batch of 100 friends in order. In the returned result, `Next` is `num1`. In the second call, set `Limit` to `100` and `Next` to `num1` to query the second batch of 100 friends in order. In the returned result, `Next` is `num2`. In the third call, set `Limit` to `100` and `Next` to `num2` to query the third batch of 50 friends in order. In the returned result, `Next` is `0`, indicating the query completes.

The flag for a paginated pull. For the first pull, set this parameter to 0. For subsequent pulls, enter the value returned from the previous pull. If Next is 0 in the returned result, the list of all friends is obtained.

For example, if FromUserId has 250 friends:

In the first call, set Limit to 100 and Next to 0 to query the first batch of 100 friends in order. In the returned result, Next is num1.
In the second call, set Limit to 100 and Next to num1 to query the second batch of 100 friends in order. In the returned result, Next is num2.
In the third call, set Limit to 100 and Next to num2 to query the third batch of 50 friends in order. In the returned result, Next is 0, indicating the query completes.

Sample request

Untitled

https://zim-api.zego.im/?Action=QueryFriendList
&Limit=100&Next=2&FromUserId=zego
&<Common request parameters>

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 friends.
Next	Number	The flag for a paginated pull. If this parameter is not `0`, information about more friends is to be returned. In this case, set this parameter as needed to pull the remaining information. If this parameter is `0`, information of all friends is returned.
FriendInfos	Array of Object	The list of friends.
└UserId	String	The user ID of the friend.
└UserName	String	The username.
└Avatar	String	The user avatar URL.
└Wording	String	The information included in the friend request.
└FriendAlias	String	The alias of the friend of `FromUserId`.
└CreateTime	Number	The friendship creation time. Unit: milliseconds.
└Attributes	Array Of Object	The attributes of the friend.
└Key	String	The key of a friend attribute.
└Value	String	The value of a friend attribute.

Sample response

Untitled

{
    "Code": 0,
    "Message": "success",
    "RequestId": "343649807833778782",
    "TotalCount": 500,
    "Next": 1,
    "FriendInfos": [
        {
            "UserId": "UserA",
            "UserName": "UserNameA",
            "Avatar": "Avatar1",
            "Wording": "Wording1",
            "FriendAlias": "FriendAlias1",
            "CreateTime": 1698310534000,
            "Attributes": [
                {
                    "Key": "k1",
                    "Value": "Value"
                },
                {
                    "Key": "k0",
                    "Value": "Value1"
                }
            ]
        },
        {
            "UserId": "UserB",
            "UserName": "UserNameB",
            "Avatar": "Avatar2",
            "Wording": "Wording1",
            "FriendAlias": "FriendAlias2",
            "CreateTime": 1698310534000,
            "Attributes": [
                {
                    "Key": "k3",
                    "Value": "Value"
                },
                {
                    "Key": "k4",
                    "Value": "Value1"
                }
            ]
        }
    ]
}

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
660000001	A common service error occurred.	Try again, or contact ZEGOCLOUD technical support.
660000002	Invalid parameter.	Check the input parameter.
660300005	The QPS limit specified in `AppID` is exceeded.	Try again later.