SendFriendApplication

POST

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

By calling this API, you can batch send friend requests to up to 20 other users for a user. If you need to increase the limit (up to 50), please contact ZEGOCLOUD Technical Support.

Note

When a user is already a one-way friend of the target user, if you call this API to send a friend request to the target user, the target user will directly become a friend of the user.

For example, users A and B were originally two-way friends. A deleted B in one-way mode, so A is a one-way friend of B, and B is not a friend of A. After calling this API to send a friend request to B, B directly becomes a friend of A without B's consent.

Each user can have a maximum of 3000 friends.

After sending a friend request, the client of the target user will receive the request notification through the following ZIM SDK callback interface:

iOS	Android	macOS	Windows
friendApplicationListChanged	onFriendApplicationListChanged	friendApplicationListChanged	onFriendApplicationListChanged

Web	Mini Program	Flutter	React Native
friendApplicationListChanged	friendApplicationListChanged	onFriendApplicationListChanged	friendApplicationListChanged

uni-app \| uni-app x	HarmonyOS
friendApplicationListChanged	friendApplicationListChanged

Note

The users corresponding to the parameters FromUserId and UserId have logged in to the ZIM service by calling the login method on the client, or have completed registration by calling the server-side API.

Note

The parameters FromUserId and UserId only support numbers, English characters, and

'!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'

QPS Limit

20 times/s

Request

Query Parameters

Action stringrequired

Possible values: [SendFriendApplication]

API prototype parameter

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

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

Send friend requests for this UserId.

FriendInfos object[]required

Possible values: <= 20

Friend structure object. Default maximum is 20.

Array[

UserId stringrequired

Possible values: <= 32 characters

Target user ID. Maximum length is 32 bytes.

Wording string

Possible values: <= 256 characters

Message from FromUserId when becoming friends with the target user. Maximum length is 256 characters.

FriendAlias string

Possible values: <= 256 characters

Remark from FromUserId to the target user, with a maximum length of 256 characters.

CreateTime number

Application creation time. This parameter can be used to import friend lists during data migration.

When it is 0, the ZIM server uses the current time.
When it is not 0, this parameter must be a millisecond timestamp and not later than the current time.

UpdateTime number

Application update time. This parameter can be used to import friend lists during data migration.

When it is 0, the ZIM server uses the current time.
When it is not 0, this parameter must be a millisecond timestamp and not later than the current time.

Attributes object[]

Possible values: <= 5

Friend attributes. Maximum is 5.

Note

The total length of Key and Value is limited to 1024 bytes. If you need to increase the limit, please contact ZEGOCLOUD Technical Support. It is recommended not to set the limit too high.

Array[

Key stringrequired

Possible values: [k0, k1, k2, k3, k4]

Friend attribute key. Can only be k0, k1, k2, k3, or k4.

Value stringrequired

Friend attribute value.

]

Responses

application/json

Schema
Example (from schema)

Schema

Code integer

Return code.

The following only lists the Code and SubCode related to the API business logic. For complete return codes, please refer to Global Return Codes.

Note

When you initiate a request to send friend requests to multiple users at the same time:

If the request is successfully sent to 1 or more users, Code will return 0. In this case, please refer to the specific information in ErrorList to confirm the operation result.

If all friend requests fail to be sent, Code will return the relevant return code. For details, please refer to Global Return Codes.

Code / SubCode	Description	Suggested Solution
660000002	Input parameter error。	Please check the input parameters。
660000011	The input user list is too large.	Please check the input user list.
660300005	The API call frequency exceeds the AppID-level limit.	Please try again later.
660500002	FromUserId is not registered.	Please register FromUserId first.
660700015	If it is code: FromUserId is not registered. If it is subCode: Target user is not registered.	If it is code: Please register FromUserId first. If it is subCode: Please register the target user first.
660800019	The number of single batch operations exceeds the limit.	Reduce the number of single batch operations.
660800020	Cannot add FromUserId as a friend, that is, the UserId in FriendInfos cannot be the same as FromUserId.	Please modify the UserId in FriendInfos that is the same as FromUserId.
660800021	FriendAlias or Wording exceeds the length limit.	Please reduce the content length of the related fields.
660800022	User ID related parameters in the parameters are duplicated.	Please delete or modify duplicate parameters.
660800023	The Key value of Attributes does not belong to k0 ~ k4.	Please modify the value of Key.
660800024	The total length of all Keys and Values in Attributes exceeds the limit.	Please reduce the content length of the related fields.
660800025	All target users are not registered, and the API call failed.	Please register the target user first.
660800026	Attributes parameter error.	Please check the input parameters。
660800027	The target user is already a friend, no need to send a friend request.	No action required.
660800028	FromUserId's friend count has reached the limit.	Cannot add more friends.
660800032	Attributes has duplicate Keys.	Please modify the Key.
660800046	The passed timestamp is greater than the current time.	Can be left blank, default is the current time.

Message string

Description of the request result.

RequestId string

Request ID.

ErrorList object[]

Failure information list.

Code is 0:
ErrorList is empty, all friend requests are successfully sent.
ErrorList is not empty, indicating that some friend requests failed to be sent. Please refer to SubCode for processing.
Code is not 0:
ErrorList is empty, indicating parameter error, API frequency limit, or system error.
ErrorList is not empty, indicating that all friend requests failed to be sent.

Array[

UserId string

Failed to send friend request to this UserID.

SubCode integer

Specific failure return code. For complete return codes, please refer to the Code description or Global Return Codes.

]

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

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

SendFriendApplication

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

Request

Query Parameters

Body

Responses​

Responses