群组管理

本文主要介绍 云上曲率即时通讯IM SDK的群组管理功能。

功能描述

云上曲率IM SDK为开发者提供如下群组管理内容:

  • 加入群组
  • 邀请加入群组
  • 获取已加入的群组
  • 移除成员出群
  • 退出群组
  • 解散群组

注意:目前客户端默认不提供创建群组的接口,由服务端创建。如果开发者需要使用客户端创建群组,请联系云上曲率。

接口说明

群事件变更通知

群组管理功能中,当出现群组成员变更、群组解散时,会接收到服务端的通知PUSH。

加入群组

用户可以使用joinGroup接口实现加入已存在的群组。

接口参数说明:

参数 含义 说明
groupId 群组ID 用户待加入的群组ID
extra 附加信息 根据加入群组方式进行处理,如果是需要审核,此处为需要审核的留言内容
attrs 自定义内容 开发者可自行增加业务内容
timeout 超时时间 加入群组的请求超时时间,单位为秒

其中,extra参数会根据群组信息设置的 “加入群组方式” 来设置。

自由加入群组

加入群组方式“自由加入” 时:

  1. 用户调用 joinGroup 直接加入群组。
  2. 加入后,群组其他成员收到由服务端推送的 群组成员加入 通知。
审核加入群组

加入群组方式“审核加入” 时:

  1. 用户调用 joinGroup 加入群组,并在extra中填写所需信息。

  2. 群主管理员 发起 ackJoinGroup回调,并进行处理。

    • ackJoinGroup接口参数说明:
    参数 含义 说明
    groupId 群组ID 用户待加入的群组ID
    fromUserId 用户ID 申请加入群组的用户ID
    agree 是否同意 群主或管理员处理是否同意该用户的入群请求
    attrs 自定义内容 开发者可自行增加业务内容
    timeout 超时时间 请求的超时时间,单位为秒
  3. 审核通过,用户加入群组,群组其他成员收到由服务端推送的 群组成员加入 通知。

  4. 审核不通过/请求超时,用户无法加入群组。

注意:加入群组请求只有在一个请求被拒绝或者失效后,才可以发起另一次同一个群组的加入请求。请求失效时间默认为 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 超时时间 邀请请求超时时间,单位为秒
群内所有用户可以邀请入群

邀请加入群组方式“群内所有成员均可以邀请” 时:

  1. 群内成员调用 inviteIntoGroup接口,邀请群外用户加入群组。

  2. 群外用户发起 ackInviteIntoGroup回调,进行处理。

    • ackInviteIntoGroup接口参数说明:

    接口参数说明:

    参数 含义 说明
    groupId 群组ID 邀请加入的群组ID
    fromId 用户ID 发起邀请的用户ID
    agree 是否同意 被邀请的用户处理是否同意加入群组
    attrs 自定义属性 开发者可配置群组信息等业务内容
    timeout 超时时间 请求的超时时间,单位为秒
  3. 邀请请求同意,用户加入群组,群组其他成员收到由服务端推送的 群组成员加入 通知。

  4. 邀请请求拒绝/请求超时,用户未加入群组。

群主或管理员可以邀请入群

邀请加入群组方式“只有群主或管理员可以邀请” 时:

  1. 群主或管理员调用 inviteIntoGroup接口,邀请群外用户加入群组。
  2. 群外用户发起 ackInviteIntoGroup回调,进行处理。
  3. 邀请请求同意,用户加入群组,群组其他成员收到由服务端推送的 群组成员加入 通知。
  4. 邀请请求拒绝/请求超时,用户未加入群组。
代码示例
-(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;