批量发送好友申请

描述

调用此接口，可为一名用户批量向至多 20 名其他用户发送好友申请。如需上调（最多可为 50），请联系 ZEGO 技术支持。

说明

当用户已为目标用户的单向好友时，如果调用此接口向目标用户发起好友申请，目标用户会直接成为用户的好友。

例如，用户 A 与 B 原本是双向好友。A 单向删除了 B，则 A 为 B 的单向好友，B 不是 A 的好友。调用此接口向 B 发起好友申请后，B 直接成为 A 的好友，无需 B 同意。

每名用户最多可以拥有 3000 名好友。

发送好友申请后，目标用户的客户端将通过以下 ZIM SDK 的回调接口接收申请通知：

iOS	Android	macOS	Windows	Web
friendApplicationListChanged	onFriendApplicationListChanged	friendApplicationListChanged	onFriendApplicationListChanged	friendApplicationListChanged
小程序	Flutter	uni-app	React Native
friendApplicationListChanged	onFriendApplicationListChanged	friendApplicationListChanged	friendApplicationListChanged

接口原型

请求方法：POST
请求地址：https://zim-api.zego.im/?Action=SendFriendApplication
传输协议：HTTPS
调用频率限制：20 次/秒。

请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式 - 公共请求参数。

参数	类型	是否必选	描述
FromUserId	String	是	为此 UserId（已注册）发送好友申请。
FriendInfos	Array of Object	是	好友结构体对象。默认上限为 20。
└UserId	String	是	目标用户 ID（已注册）。长度上限为 32 字节。
└Wording	String	否	FromUserId 对目标用户成为好友时的附言，长度上限为 256 字符。
└FriendAlias	String	否	FromUserId 对目标用户的备注，长度上限为 256 字符。
└CreateTime	Number	否	申请创建时间。此参数可在数据迁移时用于导入好友列表。为 0 时，ZIM 服务端以当前时间为准。不为 0 时，此参数需为 MS 时间戳，且不晚于当前时间。
└UpdateTime	Number	否	申请更新时间。此参数可在数据迁移时用于导入好友列表。为 0 时，ZIM 服务端以当前时间为准。不为 0 时，此参数需为 MS 时间戳，且不晚于当前时间。
└Attributes	Array of Object	否	好友属性，上限 5 个。说明 Key 的总长度与 Value 的总长度上限为 1024 字节。如需上调，请联系 ZEGO 技术支持。建议不要将上限设置过大。
└Key	String	是	好友属性的键。取值仅能为 k0、k1、k2、k3、k4。
└Value	String	是	好友属性的值。

说明

FromUserId 和 UserId 仅支持数字，英文字符和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。

请求示例

请求地址 URL：

Untitled

https://zim-api.zego.im/?Action=SendFriendApplication
&<公共请求参数>

Copied!

请求消息体：

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!

响应参数

参数	类型	描述
Code	Number	返回码。说明当您发起请求同时向多名用户发送好友申请时：如果成功向 1 名或更多用户发送申请，Code 都会返回 0。此时请参考 ErrorList 中的具体信息，确认操作结果。如果全部好友申请发送失败，Code 会返回相关返回码，具体请参考全局返回码。
Message	String	请求结果的说明信息。
RequestId	String	请求 ID。
ErrorList	Array of Object	失败信息列表。 Code 为 0： ErrorList 为空，成功发送所有好友申请。 ErrorList 不为空，表示部分好友申请发送失败，请参考 SubCode 处理。 Code 不为 0： ErrorList 为空，表示参数错误、接口频率限制、系统错误。 ErrorList 不为空，表示添加全部好友申请发送失败。
└UserID	String	向该 UserID 发送好友申请失败。
└SubCode	Number	具体失败返回码。

响应示例

Untitled

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

Copied!

返回码

以下仅列出了接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	描述	处理建议
660000002	输入参数错误。	请检查输入的参数。
660000011	输入的用户列表过大。	请检查输入的用户列表。
660300005	调用接口的频率超出了 AppID 级别限制。	请稍后再试。
660500002	`FromUserId` 未注册。	请先注册 `FromUserId`。
660700015	如果为 code：`FromUserId` 未注册。如果为 subCode：目标用户未注册。	如果为 code：请先注册 `FromUserId`。如果为 subCode：请先注册目标用户。
660800019	单次批量操作数量超过上限。	减少单次批量操作数量。
660800020	不能将 `FromUserId` 添加为好友，即 `FriendInfos` 中的 `UserId` 不能与 `FromUserId` 相同。	请修改 `FriendInfos` 中与 `FromUserId` 相同的 `UserId`。
660800021	`FriendAlias` 或 `Wording` 超过长度上限。	请缩减相关字段的内容长度。
660800022	参数中的用户 ID 相关参数重复。	请删除或修改重复参数。
660800023	`Attributes` 的 `Key` 取值不属于 k0 ~ k4。	请修改 `Key` 的值。
660800024	`Attributes` 的所有 `Key`、`Value` 总长度超过长度上限。	请缩减相关字段的内容长度。
660800025	所有目标用户均未注册过，接口调用失败。	请先注册目标用户。
660800026	`Attributes` 参数错误。	请检查输入的参数。
660800027	目标用户已经是好友，无需发起好友申请。	无需操作。
660800028	`FromUserId` 的好友数量到达上限。	无法添加更多好友。
660800032	`Attributes` 有重复的 `Key`。	请修改 `Key`。
660800046	传递的时间戳大于当前时间。	可以不填，默认是当前时间。