QueryFriendList

GET

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

Paginate and retrieve the friend list based on user ID, obtaining information such as remarks and friend relationship establishment time.

QPS Limit

20 times/s

Request

Query Parameters

Action stringrequired

Possible values: [QueryFriendList]

API prototype parameter

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

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.

application/json

Body

required

FromUserId stringrequired

Possible values: <= 32 characters

Query the friend 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).

Limit numberrequired

Possible values: >= 0 and <= 100

How many friends' information to retrieve at a time. Value range is [0, 100]. If not filled in or the value is 0 or greater than 100, the value is 100.

Next numberrequired

Pagination flag. Fill in 0 for the first time, and then fill in the Next value returned last time. When the returned Next is 0, it means the friend list retrieval is complete.

For example, if FromUserId has 250 friends, when calling this API to query:

First call: Limit is 100, Next is empty, query friends 1 ~ 100; the Next value in the returned result is num1.
Second call: Limit is 100, Next is num1, query friends 101 ~ 200; the Next value in the returned result is num2.
Third call: Limit is 100, Next is num2, query friends 201 ~ 250; query is complete, the Next in the returned result is 0.

Responses

application/json

Schema
Example (from schema)
Example

Schema

Code integer

Return code.

Return Code	Description	Suggested Solution
660000001	General business error.	Please retry or contact ZEGOCLOUD Technical Support.
660000002	Parameter error.	Please check the request parameters.
660300005	The API call frequency exceeds the AppID-level limit.	Please try again later.

Message string

Description of the request result.

RequestId string

Request ID.

TotalCount int32

Total number of current friends.

Next number

Pagination flag. Non-zero means there is still friend information not returned; 0 means all friend information has been returned.

Note

In addition to the above description, this field has no association with the list information. Do not make any other logic based on this.

FriendInfos object[]

Friend data list.

Array[

UserId string

Friend user ID.

UserName string

User name.

Avatar string

User avatar URL.

Wording string

Wording when establishing friend relationship.

FriendAlias string

FromUserId's remark for this friend.

CreateTime number

Friend relationship establishment time in milliseconds (ms).

Attributes object[]

Friend attributes.

Array[

Key string

Friend attribute key.

Value string

Friend attribute value.

]

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

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

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

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