即时通讯
  • iOS : Objective-C
  • Android
  • macOS
  • Windows
  • Web
  • 小程序
  • Flutter
  • Unity3D
  • uni-app
  • React Native
  • 产品简介
  • 下载
  • 快速开始
    • 跑通示例源码
    • 实现基本消息收发
  • 用户相关
  • 房间相关
  • 群组相关
  • 消息相关
  • 呼叫邀请
  • 会话管理
  • 缓存管理
  • 离线推送
  • 语音组件
  • 客户端 API
  • 服务端 API
  • 迁移方案
  • SDK 错误码
  • 常见问题
  • 文档中心
  • 即时通讯
  • 服务端 API
  • 用户相关
  • 批量发送好友申请

批量发送好友申请

更新时间:2024-03-06 17:42

描述

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

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

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

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

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

接口原型

  • 请求方法: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:

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

    {
        "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"
                    }
                ]
            }
        ]
    }

响应参数

参数 类型 描述
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
具体失败返回码。

响应示例

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

返回码

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

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