Batch add friends

Overview

You can call this operation to batch add up to 20 friends for a user without their consent. If you need a higher limit (50 at maximum), contact ZEGOCLOUD technical support.

Each user can have a maximum of 3000 friends.

After friends are added, the client of the user receives the notification in the following ZIM SDK callbacks.

iOS	Android	macOS	Windows
friendListChanged	onFriendListChanged	friendListChanged	onFriendListChanged
Web	Flutter
friendListChanged	onFriendListChanged

Operation prototype

Request method: POST
Request URL: https://zim-api.zego.im/?Action=AddFriends
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 for whom friends are to be added.
FriendInfos	Array of Object	Yes	The list of friends to be added. Up to 20 user IDs can be included.
└UserId	String	Yes	The ID of the registered user to be added, which cannot exceed 32 bytes in length.
└Wording	String	No	The information included in the friend request, which cannot exceed 256 characters in length.
└FriendAlias	String	No	The alias to be set for the target user, which cannot exceed 256 characters in length.
└FriendTime	Number	No	The time when the friendship was established. This parameter can be used to migrate the list of friends during data migration. If the value is set to `0`, the ZIM server uses the current time. If the value is not set to `0`, this parameter needs to be a Unix timestamp in ms and cannot be later than the current time.
└Attributes	Array of Object	No	The friend attributes. Up to five attributes are supported. Note The total length of the `Key` and `Value` parameters cannot exceed 1,024 bytes. If you need a higher limit, contact ZEGOCLOUD technical support. We recommend that you set a proper limit.
└Key	String	Yes	The key of a friend attribute. Valid values: `k0`, `k1`, `k2`, `k3`, and `k4`.
└Value	String	Yes	The value of a friend attribute.

Note

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

Sample request

Request URL:

Untitled

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

Copied!

Request body:

Untitled

{
  "FromUserId": "zego_user",
  "FriendInfos": [
      {
          "UserId": "usera1",
          "Wording": "Wording1",
          "FriendAlias": "alias1",
          "Attributes": [
              {
                  "Key": "k1",
                  "Value": "Value"
              },
              {
                  "key": "k2",
                  "Value": "Value1"
              }
          ]
      },
      {
          "UserId": "usera2",
          "Wording": "Wording2",
          "FriendAlias": "alias2",
          "Attributes": [
              {
                  "key": "k3",
                  "Value": "Value"
              },
              {
                  "key": "k0",
                  "Value": "Value1"
              }
          ]
      }
  ]
}

Copied!

Response parameters

Parameter	Type	Description
Code	Number	The return code. Note When you request to add multiple specified users at a time, take note of the following items: If one or more friends are successfully added, `0` is returned. For more information, see `ErrorList`. If all specified friends fail to be added, a corresponding code is returned. For more information, see Return codes.
Message	String	The description of the request result.
RequestId	String	The request ID.
ErrorList	Array of Object	The list of failed results. If `Code` is `0`: If `ErrorList` is empty, all specified users are successfully added. If `ErrorList` is not empty, some specified users fail to be added. In this case, see `SubCode`. If `Code` is not `0`: If `ErrorList` is empty, one or more parameters are invalid, the QPS limit is exceeded, or a system error occurs. If `ErrorList` is not empty, all specified users fail to be added.
└UserID	String	The ID of the user who fails to be added.
└SubCode	Number	The code returned when the request fails.

Sample response

Untitled

{
    "Code": 0,
    "Message": "success",
    "RequestId": "343649807833778782",
    "ErrorList": [
        {
            "UserId": "usera2",
            "SubCode": 660800022
        }
    ]
}

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.	Register `FromUserId`.
660700015	If it is a code, `FromUserId` is not registered. If it is a subcode, the target user is not registered.	If it is a code, register `FromUserId`. If it is a subcode, register the target user.
660800019	The number of users to be added at a time exceeds the limit.	Reduce the number of users to be added at a time.
660800020	The friend request cannot be sent to `FromUserId`; that is, the value of the `UserId` parameter in the `FriendInfos` parameter cannot be the same as that of the `FromUserId` parameter.	Modify the value of the `UserId` parameter in the `FriendInfos` parameter that is the same as that of the `FromUserId` parameter.
660800021	The length of the `FriendAlias` or `Wording` parameter exceeds the limit.	Reduce the parameter length.
660800022	Repeated user IDs exist.	Delete or modify repeated IDs.
660800023	The value of the `Key` parameter for the `Attributes` parameter is not `k0`, `k1`, `k2`, `k3`, or `k4`.	Modify the value of the `Key` parameter.
660800024	The total length of the `Key` and `Value` parameters for the `Attributes` parameter exceeds the limit.	Reduce the parameter length.
660800025	Failed to call the operation, as all specified users are not registered.	Register the target users.
660800026	Friend attributes are invalid.	Check the attributes.
660800027	The target user is a friend already.	No handling is required.
660800028	The number of friends of `FromUserId` reaches the limit.	No more friends can be added.
660800032	The `Attributes` parameter has repeated `Key` values.	Modify the value of the `Key` parameter.
660800046	The timestamp passed in is later than the current time.	This parameter can be left unspecified. By default, the current time is used.