Batch send friend requests

Overview

You can call this operation to batch send friend requests to up to 20 users for a user. If you need a higher limit (50 at maximum), contact ZEGOCLOUD technical support.

Note

If the target user is a one-way friend, the request is accepted upon the call.

For example, if users A and B are two-way friends, and user A deletes user B, user A becomes a one-way friend of user B, and user B is not a friend of user A. In this case, user B becomes a friend of user A after this operation is called, without the consent of user B.

Each user can have a maximum of 3000 friends.

After a friend request is sent, the client of the user receives the notification in the following ZIM SDK callbacks.

iOS	Android	macOS	Windows
friendApplicationListChanged	onFriendApplicationListChanged	friendApplicationListChanged	onFriendApplicationListChanged
Web	Flutter
friendApplicationListChanged	onFriendApplicationListChanged

Operation prototype

Request method: POST
Request URL: https://zim-api.zego.im/?Action=SendFriendApplication
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 friend requests are to be sent.
FriendInfos	Array of Object	Yes	The list of users to whom friend requests are to be sent. Up to 20 user IDs can be included.
└UserId	String	Yes	The ID of the target user (registered), 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.
└CreateTime	Number	No	The time when the request was created. 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.
└UpdateTime	Number	No	The time when the request was updated. 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=SendFriendApplication
&<Common request parameters>

Copied!

Request body:

Untitled

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

Copied!

Response parameters

Parameter	Type	Description
Code	Number	The return code. Note When you send friend requests to multiple users at a time, take note of the following items: If one or more requests are successfully sent, `0` is returned. For more information, see `ErrorList`. If all friend requests fail to be sent, 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 friend requests are successfully sent. If `ErrorList` is not empty, some friend requests fail to be sent. 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 friend requests fail to be sent.
└UserID	String	The ID of the user to whom the friend request fails to be sent.
└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.
660000011	Too many users are included in the list.	Check the number of users.
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 friend requests to be sent at a time exceeds the limit.	Reduce the number of friend requests to be sent 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 target users are not registered.	Register the target users.
660800026	The `Attributes` parameter is invalid	Check the input parameter.
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.