群组管理
Update:
本文主要介绍 云上曲率即时通讯IM SDK的群组管理功能。
功能描述
云上曲率IM SDK为开发者提供如下群组管理内容:
- 加入群组
- 邀请加入群组
- 获取已加入的群组
- 移除成员出群
- 退出群组
- 解散群组
注意:目前客户端默认不提供创建群组的接口,由服务端创建。如果开发者需要使用客户端创建群组,请联系云上曲率。
接口说明
群事件变更通知
群组管理功能中,当出现群组成员变更、群组解散时,会接收到服务端的通知PUSH。
加入群组
用户可以使用joinGroup
接口实现加入已存在的群组。
接口参数说明:
参数
含义
说明
groupId
群组ID
用户待加入的群组ID
extra
附加信息
根据加入群组方式进行处理,如果是需要审核,此处为需要审核的留言内容
attrs
自定义内容
开发者可自行增加业务内容
timeout
超时时间
加入群组的请求超时时间,单位为秒
其中,extra
参数会根据群组信息设置的 “加入群组方式” 来设置。
自由加入群组
当 加入群组方式 为 “自由加入” 时:
- 用户调用
joinGroup
直接加入群组。
- 加入后,群组其他成员收到由服务端推送的 群组成员加入 通知。
审核加入群组
当 加入群组方式 为 “审核加入” 时:
-
用户调用 joinGroup
加入群组,并在extra
中填写所需信息。
-
群主 或 管理员 发起 ackJoinGroup
回调,并进行处理。
ackJoinGroup
接口参数说明:
参数
含义
说明
groupId
群组ID
用户待加入的群组ID
fromUserId
用户ID
申请加入群组的用户ID
agree
是否同意
群主或管理员处理是否同意该用户的入群请求
attrs
自定义内容
开发者可自行增加业务内容
timeout
超时时间
请求的超时时间,单位为秒
-
审核通过,用户加入群组,群组其他成员收到由服务端推送的 群组成员加入 通知。
-
审核不通过/请求超时,用户无法加入群组。
注意:加入群组请求只有在一个请求被拒绝或者失效后,才可以发起另一次同一个群组的加入请求。请求失效时间默认为 24 小时。
拒绝加入群组
当 加入群组方式 为 “拒绝加入” 时,用户调用 joinGroup
无法加入群组。
代码示例
-(void)joinGroup:(NSNumber * _Nonnull)groupId
extra:(NSString * _Nullable)extra
attrs:(NSString * _Nullable)attrs
timeout:(int)timeout
success:(void(^)(void))successCallback
fail:(IMAnswerFailCallBack)failCallback;
-(void)ackjoinGroup:(NSNumber * _Nonnull)groupId
from:(NSNumber * _Nullable)fromId
agree:(BOOL)agree
attrs:(NSString * _Nullable)attrs
timeout:(int)timeout
success:(void(^)(void))successCallback
fail:(IMAnswerFailCallBack)failCallback;
邀请加入群组
用户可以使用inviteIntoGroup
接口实现邀请其他非群组用户加入该用户已加入的群组。
注意:邀请加入群组的用户需要根据群组信息 邀请加入群组方式
中设置的方式来进行调用。
接口参数说明:
参数
含义
说明
groupId
群组ID
邀请用户加入的群组ID
uids
用户ID
邀请入群的用户ID
extra
附加信息
邀请用户入群时,可以添加的附加内容
attrs
自定义内容
开发者可配置群组信息等业务内容
timeout
超时时间
邀请请求超时时间,单位为秒
群内所有用户可以邀请入群
当 邀请加入群组方式 为 “群内所有成员均可以邀请” 时:
-
群内成员调用 inviteIntoGroup
接口,邀请群外用户加入群组。
-
群外用户发起 ackInviteIntoGroup
回调,进行处理。
ackInviteIntoGroup
接口参数说明:
接口参数说明:
参数
含义
说明
groupId
群组ID
邀请加入的群组ID
fromId
用户ID
发起邀请的用户ID
agree
是否同意
被邀请的用户处理是否同意加入群组
attrs
自定义属性
开发者可配置群组信息等业务内容
timeout
超时时间
请求的超时时间,单位为秒
-
邀请请求同意,用户加入群组,群组其他成员收到由服务端推送的 群组成员加入 通知。
-
邀请请求拒绝/请求超时,用户未加入群组。
群主或管理员可以邀请入群
当 邀请加入群组方式 为 “只有群主或管理员可以邀请” 时:
- 群主或管理员调用
inviteIntoGroup
接口,邀请群外用户加入群组。
- 群外用户发起
ackInviteIntoGroup
回调,进行处理。
- 邀请请求同意,用户加入群组,群组其他成员收到由服务端推送的 群组成员加入 通知。
- 邀请请求拒绝/请求超时,用户未加入群组。
代码示例
-(void)inviteGroup:(NSNumber * _Nonnull)groupId
uids:(NSArray <NSNumber*> * _Nullable)uids
extra:(NSString * _Nullable)extra
attrs:(NSString * _Nullable)attrs
timeout:(int)timeout
success:(void(^)(void))successCallback
fail:(IMAnswerFailCallBack)failCallback;
-(void)ackinviteGroup:(NSNumber * _Nonnull)groupId
from:(NSNumber * _Nullable)fromId
agree:(BOOL)agree
attrs:(NSString * _Nullable)attrs
timeout:(int)timeout
success:(void(^)(void))successCallback
fail:(IMAnswerFailCallBack)failCallback;
获取已加入的群组
用户可以通过getGroupList
接口获取用户已经加入的所有群组,以列表形式返回。
接口参数说明:
参数
含义
说明
timeout
超时时间
请求的超时时间,单位为秒
代码示例
-(void)getGroupList:(int)timeout
success:(void(^)(NSArray * _Nullable groupArray))successCallback
fail:(IMAnswerFailCallBack)failCallback;
获取加入群组请求列表
当有入群请求未处理时,群主 或 管理员 可以通过调用getGroupApplyList
接口获取所管理的群组接收到的入群请求列表。
注意:该接口只会获取到未处理的请求,已处理的请求或者拉取到再处理的请求会删除。如果某请求超时,此接口也不会获取到该请求。
接口参数说明:
参数
含义
说明
groupId
群组ID
获取入群请求的群组ID
timeout
超时时间
请求的超时时间,单位为秒
代码示例
-(void)getGroupApplyList:(NSNumber * _Nonnull)groupId
timeout:(int)timeout
success:(void(^)(NSArray <IMGetGroupApplyList * > * array))successCallback
fail:(IMAnswerFailCallBack)failCallback;
获取申请加入群组的请求列表
用户可以通过调用getGroupRequestList
接口获取到自己申请加入群组的请求列表。如果请求已经处理(包括已加入群组或被拒绝),则该请求不会通过此接口获取到。
注意:如果某请求超时,此接口不会获取到该请求。
接口参数说明:
参数
含义
说明
timeout
超时时间
请求的超时时间,单位为秒
代码示例
-(void)getGroupRequestList:(int)timeout
success:(void(^)(NSArray <IMGetGroupRequestList * > * array))successCallback
fail:(IMAnswerFailCallBack)failCallback;
获取自己被邀请入群的请求列表
用户可以通过getGroupInviteList
接口获取到被哪些群组邀请的请求列表。如果用户已经处理过请求,包括同意邀请或拒绝邀请,那么这些处理过的请求不会通过此接口获取。
注意:如果某请求超时,此接口不会获取到该请求。
接口参数说明:
参数
含义
说明
timeout
超时时间
请求的超时时间,单位为秒
代码示例
-(void)getGroupInviteList:(int)timeout
success:(void(^)(NSArray <IMGetGroupInviteList * > * array))successCallback
fail:(IMAnswerFailCallBack)failCallback;
移除成员出群
只有群主或管理员可以通过removeGroupMembers
接口将群组成员移除出群。
当群组成员被移除出群后,群组内其他成员会收到由服务端推送的 群组成员被移出群组 通知。
注意:群主可以将管理员和普通成员移除出群,管理员只可以将普通成员移除出群。
接口参数说明:
参数
含义
说明
groupId
群组ID
需要移除成员出群的群组ID
uids
用户ID
需要移除出群的用户ID
timeout
超时时间
请求的超时时间,单位为秒
代码示例
-(void)removeGroupMembers:(NSNumber * _Nonnull)groupId
uids:(NSArray <NSNumber*>*)uids
timeout:(int)timeout
success:(void(^)(void))successCallback
fail:(IMAnswerFailCallBack)failCallback;
退出群组
用户可以通过leaveGroup
接口退出已加入的群组。
退出群组后,用户不会再接收该群组的消息推送,并且无法再从服务端获取该群组会话和历史消息。
当群组成员成功退出群组后,群组内其他成员会收到由服务端推送的 群组成员退出 通知。
注意:当用户是所在群组的群主角色时,如果要退出群组,需要先将群主身份角色转移给群组内其他用户,然后才可以退出群组。
接口参数说明:
参数
含义
说明
groupId
群组ID
要退出的群组ID
timeout
超时时间
请求的超时时间,单位为秒
代码示例
-(void)leaveGroup:(NSNumber * _Nonnull)groupId
timeout:(int)timeout
success:(void(^)(void))successCallback
fail:(IMAnswerFailCallBack)failCallback;
解散群组
只有群主可以通过dismissGroup
接口解散所在的群组。
群组解散后,群组内其他成员会收到由服务端推送的 群组已解散 通知,用户不会再接收该群组的消息推送,并且无法再从服务端获取该群组会话和历史消息。
接口参数说明:
参数
含义
说明
groupId
群组ID
要解散的群组ID
timeout
超时时间
请求的超时时间,单位为秒
代码示例
-(void)dismissGroup:(NSNumber * _Nonnull)groupId
timeout:(int)timeout
success:(void(^)(void))successCallback
fail:(IMAnswerFailCallBack)failCallback;
本文主要介绍 云上曲率即时通讯IM SDK的群组管理功能。
功能描述
云上曲率IM SDK为开发者提供如下群组管理内容:
- 加入群组
- 邀请加入群组
- 获取已加入的群组
- 移除成员出群
- 退出群组
- 解散群组
注意:目前客户端默认不提供创建群组的接口,由服务端创建。如果开发者需要使用客户端创建群组,请联系云上曲率。
接口说明
群事件变更通知
群组管理功能中,当出现群组成员变更、群组解散时,会接收到服务端的通知PUSH。
加入群组
用户可以使用joinGroup
接口实现加入已存在的群组。
接口参数说明:
参数 | 含义 | 说明 |
---|---|---|
groupId | 群组ID | 用户待加入的群组ID |
extra | 附加信息 | 根据加入群组方式进行处理,如果是需要审核,此处为需要审核的留言内容 |
attrs | 自定义内容 | 开发者可自行增加业务内容 |
timeout | 超时时间 | 加入群组的请求超时时间,单位为秒 |
其中,extra
参数会根据群组信息设置的 “加入群组方式” 来设置。
自由加入群组
当 加入群组方式 为 “自由加入” 时:
- 用户调用
joinGroup
直接加入群组。 - 加入后,群组其他成员收到由服务端推送的 群组成员加入 通知。
审核加入群组
当 加入群组方式 为 “审核加入” 时:
-
用户调用
joinGroup
加入群组,并在extra
中填写所需信息。 -
群主 或 管理员 发起
ackJoinGroup
回调,并进行处理。ackJoinGroup
接口参数说明:
参数 含义 说明 groupId 群组ID 用户待加入的群组ID fromUserId 用户ID 申请加入群组的用户ID agree 是否同意 群主或管理员处理是否同意该用户的入群请求 attrs 自定义内容 开发者可自行增加业务内容 timeout 超时时间 请求的超时时间,单位为秒 -
审核通过,用户加入群组,群组其他成员收到由服务端推送的 群组成员加入 通知。
-
审核不通过/请求超时,用户无法加入群组。
注意:加入群组请求只有在一个请求被拒绝或者失效后,才可以发起另一次同一个群组的加入请求。请求失效时间默认为 24 小时。
拒绝加入群组
当 加入群组方式 为 “拒绝加入” 时,用户调用 joinGroup
无法加入群组。
代码示例
-(void)joinGroup:(NSNumber * _Nonnull)groupId
extra:(NSString * _Nullable)extra
attrs:(NSString * _Nullable)attrs
timeout:(int)timeout
success:(void(^)(void))successCallback
fail:(IMAnswerFailCallBack)failCallback;
-(void)ackjoinGroup:(NSNumber * _Nonnull)groupId
from:(NSNumber * _Nullable)fromId
agree:(BOOL)agree
attrs:(NSString * _Nullable)attrs
timeout:(int)timeout
success:(void(^)(void))successCallback
fail:(IMAnswerFailCallBack)failCallback;
邀请加入群组
用户可以使用inviteIntoGroup
接口实现邀请其他非群组用户加入该用户已加入的群组。
注意:邀请加入群组的用户需要根据群组信息
邀请加入群组方式
中设置的方式来进行调用。
接口参数说明:
参数 | 含义 | 说明 |
---|---|---|
groupId | 群组ID | 邀请用户加入的群组ID |
uids | 用户ID | 邀请入群的用户ID |
extra | 附加信息 | 邀请用户入群时,可以添加的附加内容 |
attrs | 自定义内容 | 开发者可配置群组信息等业务内容 |
timeout | 超时时间 | 邀请请求超时时间,单位为秒 |
群内所有用户可以邀请入群
当 邀请加入群组方式 为 “群内所有成员均可以邀请” 时:
-
群内成员调用
inviteIntoGroup
接口,邀请群外用户加入群组。 -
群外用户发起
ackInviteIntoGroup
回调,进行处理。ackInviteIntoGroup
接口参数说明:
接口参数说明:
参数 含义 说明 groupId 群组ID 邀请加入的群组ID fromId 用户ID 发起邀请的用户ID agree 是否同意 被邀请的用户处理是否同意加入群组 attrs 自定义属性 开发者可配置群组信息等业务内容 timeout 超时时间 请求的超时时间,单位为秒 -
邀请请求同意,用户加入群组,群组其他成员收到由服务端推送的 群组成员加入 通知。
-
邀请请求拒绝/请求超时,用户未加入群组。
群主或管理员可以邀请入群
当 邀请加入群组方式 为 “只有群主或管理员可以邀请” 时:
- 群主或管理员调用
inviteIntoGroup
接口,邀请群外用户加入群组。 - 群外用户发起
ackInviteIntoGroup
回调,进行处理。 - 邀请请求同意,用户加入群组,群组其他成员收到由服务端推送的 群组成员加入 通知。
- 邀请请求拒绝/请求超时,用户未加入群组。
代码示例
-(void)inviteGroup:(NSNumber * _Nonnull)groupId
uids:(NSArray <NSNumber*> * _Nullable)uids
extra:(NSString * _Nullable)extra
attrs:(NSString * _Nullable)attrs
timeout:(int)timeout
success:(void(^)(void))successCallback
fail:(IMAnswerFailCallBack)failCallback;
-(void)ackinviteGroup:(NSNumber * _Nonnull)groupId
from:(NSNumber * _Nullable)fromId
agree:(BOOL)agree
attrs:(NSString * _Nullable)attrs
timeout:(int)timeout
success:(void(^)(void))successCallback
fail:(IMAnswerFailCallBack)failCallback;
获取已加入的群组
用户可以通过getGroupList
接口获取用户已经加入的所有群组,以列表形式返回。
接口参数说明:
参数 | 含义 | 说明 |
---|---|---|
timeout | 超时时间 | 请求的超时时间,单位为秒 |
代码示例
-(void)getGroupList:(int)timeout
success:(void(^)(NSArray * _Nullable groupArray))successCallback
fail:(IMAnswerFailCallBack)failCallback;
获取加入群组请求列表
当有入群请求未处理时,群主 或 管理员 可以通过调用getGroupApplyList
接口获取所管理的群组接收到的入群请求列表。
注意:该接口只会获取到未处理的请求,已处理的请求或者拉取到再处理的请求会删除。如果某请求超时,此接口也不会获取到该请求。
接口参数说明:
参数 | 含义 | 说明 |
---|---|---|
groupId | 群组ID | 获取入群请求的群组ID |
timeout | 超时时间 | 请求的超时时间,单位为秒 |
代码示例
-(void)getGroupApplyList:(NSNumber * _Nonnull)groupId
timeout:(int)timeout
success:(void(^)(NSArray <IMGetGroupApplyList * > * array))successCallback
fail:(IMAnswerFailCallBack)failCallback;
获取申请加入群组的请求列表
用户可以通过调用getGroupRequestList
接口获取到自己申请加入群组的请求列表。如果请求已经处理(包括已加入群组或被拒绝),则该请求不会通过此接口获取到。
注意:如果某请求超时,此接口不会获取到该请求。
接口参数说明:
参数 | 含义 | 说明 |
---|---|---|
timeout | 超时时间 | 请求的超时时间,单位为秒 |
代码示例
-(void)getGroupRequestList:(int)timeout
success:(void(^)(NSArray <IMGetGroupRequestList * > * array))successCallback
fail:(IMAnswerFailCallBack)failCallback;
获取自己被邀请入群的请求列表
用户可以通过getGroupInviteList
接口获取到被哪些群组邀请的请求列表。如果用户已经处理过请求,包括同意邀请或拒绝邀请,那么这些处理过的请求不会通过此接口获取。
注意:如果某请求超时,此接口不会获取到该请求。
接口参数说明:
参数 | 含义 | 说明 |
---|---|---|
timeout | 超时时间 | 请求的超时时间,单位为秒 |
代码示例
-(void)getGroupInviteList:(int)timeout
success:(void(^)(NSArray <IMGetGroupInviteList * > * array))successCallback
fail:(IMAnswerFailCallBack)failCallback;
移除成员出群
只有群主或管理员可以通过removeGroupMembers
接口将群组成员移除出群。
当群组成员被移除出群后,群组内其他成员会收到由服务端推送的 群组成员被移出群组 通知。
注意:群主可以将管理员和普通成员移除出群,管理员只可以将普通成员移除出群。
接口参数说明:
参数 | 含义 | 说明 |
---|---|---|
groupId | 群组ID | 需要移除成员出群的群组ID |
uids | 用户ID | 需要移除出群的用户ID |
timeout | 超时时间 | 请求的超时时间,单位为秒 |
代码示例
-(void)removeGroupMembers:(NSNumber * _Nonnull)groupId
uids:(NSArray <NSNumber*>*)uids
timeout:(int)timeout
success:(void(^)(void))successCallback
fail:(IMAnswerFailCallBack)failCallback;
退出群组
用户可以通过leaveGroup
接口退出已加入的群组。
退出群组后,用户不会再接收该群组的消息推送,并且无法再从服务端获取该群组会话和历史消息。
当群组成员成功退出群组后,群组内其他成员会收到由服务端推送的 群组成员退出 通知。
注意:当用户是所在群组的群主角色时,如果要退出群组,需要先将群主身份角色转移给群组内其他用户,然后才可以退出群组。
接口参数说明:
参数 | 含义 | 说明 |
---|---|---|
groupId | 群组ID | 要退出的群组ID |
timeout | 超时时间 | 请求的超时时间,单位为秒 |
代码示例
-(void)leaveGroup:(NSNumber * _Nonnull)groupId
timeout:(int)timeout
success:(void(^)(void))successCallback
fail:(IMAnswerFailCallBack)failCallback;
解散群组
只有群主可以通过dismissGroup
接口解散所在的群组。
群组解散后,群组内其他成员会收到由服务端推送的 群组已解散 通知,用户不会再接收该群组的消息推送,并且无法再从服务端获取该群组会话和历史消息。
接口参数说明:
参数 | 含义 | 说明 |
---|---|---|
groupId | 群组ID | 要解散的群组ID |
timeout | 超时时间 | 请求的超时时间,单位为秒 |
代码示例
-(void)dismissGroup:(NSNumber * _Nonnull)groupId
timeout:(int)timeout
success:(void(^)(void))successCallback
fail:(IMAnswerFailCallBack)failCallback;