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.
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 | Web |
---|---|---|---|---|
Flutter | ||||
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.
|
UpdateTime |
Number |
No |
The time when the request was updated. This parameter can be used to migrate the list of friends during data migration.
|
Attributes |
Array of Object |
No |
The friend attributes. Up to five attributes are supported. 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. |
The FromUserId
and UserId
parameters can contain only digits, letters, and the following characters: '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', ' ', '{', '}', '|', '~'.
Request URL:
https://zim-api.zego.im/?Action=SendFriendApplication
&<Common request parameters>
Request body:
{
"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"
}
]
}
]
}
Parameter | Type | Description |
---|---|---|
Code |
Number |
The return code. When you send friend requests to multiple users at a time, take note of the following items:
|
Message |
String |
The description of the request result. |
RequestId |
String |
The request ID. |
ErrorList |
Array of Object |
The list of failed results.
|
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. |
{
"Code": 0,
"Message": "success",
"RequestId": "343649807833778782",
"ErrorList": [
{
"UserId": "usera2",
"SubCode": 660800022
}
]
}
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 |
|
|
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. |