Supergroup features

Supergroup Overview

Supergroup corresponds to the management category of NIMSuper teamManager. Supergroup is a feature for the scene of large-scale team chat. At present, it supports at most 5000-person team chat. Due to the particularity, it cannot support all the management features of advanced teams. The supergroup currently only supports two identities: Team Owner and ordinary Members.

Create a team

Supergroup should be created with API at the server. No API is provided on the client for the creation.

Get team

Since NIM SDK will synchronize local team messages at the startup, a team may be fetched by calling the local cache API. SDK provides massive team APIs required to fetch it and The APIs required for inquiry based on a team ID. SDK also provides The APIs for remote access to team messages.

Get All Teams Locally

Prototype

@protocol NIMSuper teamManager <NSObject>
/**
 * Get all teams
 *
 * @return - Return all teams
 */
- (nullable NSArray<NIMTeam *> *)allMyTeams;
@end

Get a specified team locally

@protocol NIMSuper teamManager <NSObject>
/**
 * Get detailed team profile by team ID
 *
 * @param teamId - Team ID
 *
 * @return - Team information
 */
- (nullable NIMTeam *)teamById:(NSString *)teamId;
@end

Parameter List

Parameter	Type	Description
teamId	NSString	Team ID

Get a specified team from the cloud

@protocol NIMSuper teamManager <NSObject>
/**
 * Get team profile
 *
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 */
- (void)fetchTeamInfo:(NSString *)teamId 
           completion:(nullable NIMTeamGetInfoHandler)completion
@end        

Dismiss a team

Supergroup should be dismissed with API at the server. No API is provided on the client for the dissolution.

Manage team members

Joining a team

Apply for joining a team

@protocol NIMSuper teamManager <NSObject>
/**
 * Team application
 *
 * @param teamId - Team ID
 * @param message - Apply for messages
 * @param completion - Callback that is returned after completion
 */
- (void)applyToTeam:(NSString *)teamId
            message:(NSString *)message
         completion:(nullable NIMTeamApplyHandler)completion;
@end

Parameter List

Parameter	Type	Description
teamId	NSString	Team ID
message	NSString	Application message
completion	NIMTeamApplyHandler	Callback after completion

Verify team application

Approve application

@protocol NIMSuper teamManager <NSObject>
/**
 * Approve team application
 *
 * @param teamId - Team ID
 * @param userId - Applied user ID
 * @param completion - Callback that is returned after completion
 */
- (void)passApplyToTeam:(NSString *)teamId
                 userId:(NSString *)userId
             completion:(nullable NIMTeamApplyHandler)completion;
@end

Parameter List

Parameter	Type	Description
teamId	NSString	Team ID
userId	NSString	User ID
completion	NIMTeamApplyHandler	Callback after completion

Reject the application

@protocol NIMSuper teamManager <NSObject>
/**
 * Reject a team application
 *
 * @param teamId - Team ID
 * @param userId - Applied user ID
 * @param rejectReason - Reason for rejection
 * @param completion - Callback that is returned after completion
 */
- (void)rejectApplyToTeam:(NSString *)teamId
                   userId:(NSString *)userId
             rejectReason:(NSString*)rejectReason
               completion:(nullable NIMTeamHandler)completion;
@end

Parameter List

Parameter	Type	Description
teamId	NSString	Team ID
userId	NSString	User ID
rejectReason	NSString	Reject reason
completion	NIMTeamHandler	Callback after completion

Invite to join a team

@protocol NIMSuper teamManager <NSObject>
/**
 * Invite users to a team
 *
 * @param users - List of user IDs
 * @param teamId - Team ID
 * @param postscript - Postscript for invitation
 * @param attach - Extension message
 * @param completion - Callback that is returned after completion
 */
- (void)addUsers:(NSArray<NSString *> *)users
          toTeam:(NSString *)teamId
      postscript:(nullable NSString *)postscript
          attach:(nullable NSString *)attach
      completion:(nullable NIMTeamMemberHandler)completion;
@end

Parameter List

Parameter	Type	Description
users	NSArray<NSString *>	List of user ID
teamId	NSString	Team ID
postscript	NSString	Invitation P.S.
attach	NSString	Extend messages
completion	NIMTeamMemberHandler	Callback after completion

Verify the application for joining a team

Accept a team invitation

@protocol NIMSuper teamManager <NSObject>
/**
 * Accept a team invitation
 *
 * @param teamId - Team ID
 * @param inviterId - Inviter ID
 * @param completion - Callback that is returned after completion
 */
- (void)acceptInviteWithTeam:(NSString*)teamId
                   inviterId:(NSString*)inviterId
                  completion:(nullable NIMTeamHandler)completion;
@end

Parameter List

Parameter	Type	Description
teamId	NSString	Team ID
inviterId	NSString	Invitor ID
completion	NIMTeamHandler	Callback after completion

Reject team invitation

@protocol NIMSuper teamManager <NSObject>
/**
 * Reject team invitation
 *
 * @param teamId - Team ID
 * @param inviterId - Inviter ID
 * @param rejectReason - Reason for rejection
 * @param completion - Callback that is returned after completion
 */
- (void)rejectInviteWithTeam:(NSString*)teamId
                   inviterId:(NSString*)inviterId
                rejectReason:(NSString*)rejectReason
                  completion:(nullable NIMTeamHandler)completion;
@end

Parameter List

Parameter	Type	Description
teamId	NSString	Team ID
inviterId	NSString	Invitor ID
rejectReason	NSString	Reject reason
completion	NIMTeamHandler	Callback after completion

Remove a team member

@protocol NIMSuper teamManager <NSObject>
/**
 * Remove members from a team
 *
 * @param users - List of user IDs to be removed
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 */
- (void)kickUsers:(NSArray<NSString *> *)users
         fromTeam:(NSString *)teamId
       completion:(NIMSuper teamHandler)completion
@end       

Session information of users kicked out of the team will be retained, but such users will longer receive any message concerning the team.

Parameter List

Parameter	Type	Description
users	NSArray<NSString *>	List of user ID to be removed
teamId	NSString	Team ID
completion	NIMSuper teamHandler	Callback after completion

Leave a team

User withdrawal

@protocol NIMSuper teamManager <NSObject>
/**
 * Leave a team
 *
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 */
- (void)quitTeam:(NSString *)teamId
      completion:(NIMSuper teamHandler)completion
@end      

Parameter List

Parameter	Type	Description
teamId	NSString	Team ID
completion	NIMSuper teamHandler	Callback after completion

Upon the successful withdrawal of a user from the team, related session information will be retained, but no message concerning the team will be received any longer.

Get team members

Differing from user data, team member information is mainly associated with a team. About a user, there is a difference among different teams in his/her information as a team member. Team member information includes a nickname, joining time, team member type, etc.

Prototype

@interface NIMSuper teamMember : NSObject
/**
 * Team ID
 */
@property (nullable,nonatomic,copy,readonly)     NSString *teamId;

/**
 * Team member ID
 */
@property (nullable,nonatomic,copy,readonly)     NSString *userId;

/**
 * Inviter ID
 * @discussion - The field is valid only when you are a member. It is not allowed to view the inviter of other team members
 */
@property (nullable,nonatomic,copy,readonly)     NSString *inviter;

/**
 * Team nickname
 */
@property (nullable,nonatomic,copy)     NSString *nickname;

/**
 * Time of joining in a team
 */
@property (nonatomic,assign,readonly)    NSTimeInterval createTime;


/**
 * Team custom information of a new member
 */
@property (nullable,nonatomic,copy)    NSString *customInfo;

@end

Property List

Parameter	Type	Description
teamId	NSString	Team ID
userId	NSString	Team member ID
nickname	NSString	Team nickname
isMuted	BOOL	It determines whether a user is muted
createTime	NSTimeInterval	Joining time
customInfo	NSString	New member custom information

For team members, SDK makes no warranties that there is local data, and team members will be synchronized at each login. SDK will cache data locally for the team members who have been synchronized or fetched actively and remotely.

In case of any change in the team member information cached locally, the upper level will be notified with the callback of NIMSuper teamManagerDelegate.

Get the list of team members

@protocol NIMSuper teamManager <NSObject>
/**
 * Get team members
 *
 * @param teamId - Team ID
 * @param option - Option of query by paging.
 * @param completion - Callback that is returned after completion
 */
- (void)fetchTeamMembers:(NSString *)teamId
                  option:(NIMTeamGetMemberOption *)option
              completion:(nullable NIMSuper teamMemberHandler)completion;
@end              

Parameter List

Parameter	Type	Description
teamId	NSString	Team ID
option	NIMTeamGetMemberOption	Paging query option
completion	NIMSuper teamMemberHandler	Callback after completion

In most cases, the request is read and cached locally, synchronized, and returned. However, due to a large amount of team member information, SDK delays the pull after login. Since SDK is probably unable to timely cache team member information due to network situations and other issues, the request will be an asynchronous operation with network request (increment request). The API will request team user profile that has not been cached locally, without triggering - (void)onUserInfoChanged: Callback.

Only the data concerning the team under the trusteeship of CommsEase server is fetched. Developers should display such data with The API in combination with the self-managed user data.

Get a specified team member

@protocol NIMSuper teamManager <NSObject>
/**
 * Get information from a single team member. The information of team members cached in the local database is returned. If there is not related data in the local database, nil will be returned.
 *
 * @param userId - User ID     
 * @param teamId - Team ID
 */
- (nullable NIMTeamMember *)teamMember:(NSString *)userId 
                                inTeam:(NSString *)teamId;
@end              

Update team member information

@protocol NIMSuper teamManager <NSObject>
/**
 * Update member nickname in a team
 *
 * @param userId - Team member ID
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 */
- (void)updateMyNick:(NSString *)userId
              inTeam:(NSString *)teamId
          completion:(NIMSuper teamHandler)completion
@end        

Parameter List

Parameter	Type	Description
userId	NSString	User ID
teamId	NSString	Team ID
completion	NIMSuper teamHandler	Callback after completion

• Update the nickname of a team member

@protocol NIMSuper teamManager <NSObject>
 * Update your nickname in a team
 *
 * @param userId - Team member ID
 * @param newNick - Nickname of a new team member
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 */
- (void)updateUserNick:(NSString *)userId 
               newNick:(NSString *)newNick 
                inTeam:(NSString *)teamId 
            completion:(nullable NIMTeamHandler)completion
@end                    

• Update the team member custom attribute

@protocol NIMSuper teamManager <NSObject>
/**
 * Update your custom attribute in a team
 *
 * @param newInfo - New custom attribute
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 */
- (void)updateMyCustomInfo:(NSString *)newInfo 
                    inTeam:(NSString *)teamId 
                completion:(nullable NIMTeamHandler)completion
@end                    

Monitor team member changes

@protocol NIMTeamManagerDelegate <NSObject>
/**
 * A callback for changing team members, including number change and change in member attribute.
 *
 * @param team - Changed team
 */
- (void)onTeamMemberChanged:(NIMSuper team *)team;
@end

Judge the existence in team

Judge whether it is my team based on the team ID

@protocol NIMSuper teamManager <NSObject>
/**
 * Determine your team by team ID
 *
 * @param teamId - Team ID
 *
 * @return - It determines that you are in a team.
 */
- (BOOL)isMyTeam:(NSString *)teamId;
@end

Parameter List

Parameter	Type	Description
teamId	NSString	Team ID

Ownership transfer

@protocol NIMSuper teamManager <NSObject>
/**
 * Transfer a team owner
 *
 * @param teamId - Team ID
 * @param newOwnerId - New team owner ID
 * @param isLeave - It determines that members leave a team synchronously.
 * @param completion - Callback that is returned after completion
 */
- (void)transferManagerWithTeam:(NSString *)teamId
                     newOwnerId:(NSString *)newOwnerId
                        isLeave:(BOOL)isLeave
                     completion:(nullable NIMTeamHandler)completion;
@end

Parameter List

Parameter	Type	Description
teamId	NSString	Team ID
newOwnerId	NSString	New owner ID
isLeave	BOOL	Synchronously leave the team or not
completion	NIMSuper teamHandler	Callback after completion

Add an administrator

@protocol NIMSuper teamManager <NSObject>
/**
 * Add an administrator
 *
 * @param teamId - Team ID
 * @param users - List of user IDs to be added as administrators
 * @param completion - Callback that is returned after completion
 */
- (void)addManagersToTeam:(NSString *)teamId
                    users:(NSArray<NSString *> *)users
               completion:(nullable NIMTeamHandler)completion;
@end

Parameter List

Parameter	Type	Description
users	NSArray<NSString *>	List of user ID required to be added as an administrator
teamId	NSString	Team ID
completion	NIMSuper teamHandler	Callback after completion

Remove an administrator

@protocol NIMSuper teamManager <NSObject>
/**
 * Remove manager
 *
 * @param teamId - Team ID
 * @param users - List of user IDs for administrators to be removed
 * @param completion - Callback that is returned after completion
 */
- (void)removeManagersFromTeam:(NSString *)teamId
                         users:(NSArray<NSString *> *)users
                    completion:(nullable NIMTeamHandler)completion;
@end

Parameter List

Parameter	Type	Description
users	NSArray<NSString *>	List of user ID to be removed from the list of administrators
teamId	NSString	Team ID
completion	NIMSuper teamHandler	Callback after completion

Mute

Mute specified members

@protocol NIMSuper teamManager <NSObject>
/**
 * Team members are muted.
 *
 * @param mute - It determines that team members are muted.
 * @param userId - User ID
 * @param teamId - Team ID
 * @param completion - Returned callback after completion of experimental operation
 * @discussion - If the operation is successful, the CommsEase server will send team notification message for mute.
 */
- (void)updateMuteState:(BOOL)mute
                userIds:(NSArray<NSString *> *)userIds
                 inTeam:(NSString *)teamId
             completion:(nullable NIMTeamHandler)completion;
@end

Parameter List

Parameter	Type	Description
mute	BOOL	Whether to mute users
users	NSArray<NSString *>	User ID
teamId	NSString	Team ID
completion	NIMSuper teamHandler	Callback after completion

Mute all team members

@protocol NIMSuper teamManager <NSObject>
/**
 * Mute all team members
 *
 * @param mute - It determines that team members are muted.
 * @param teamId - Team ID
 * @param completion - Returned callback after completion of experimental operation
 * @discussion - If the operation is successful, the CommsEase server will send team notification messages for mute.
 */
- (void)updateMuteState:(BOOL)mute
                inTeam:(NSString *)teamId
            completion:(nullable NIMTeamHandler)completion;
@end

Parameter List

Parameter	Type	Description
mute	BOOL	Whether to mute users
teamId	NSString	Team ID
completion	NIMSuper teamHandler	Callback after completion

Query mute status

@protocol NIMSuper teamManager <NSObject>
/**
 * Get the list of muted team members
 *
 * @param teamId - Team ID
 * @param completion - Returned callback after completion of experimental operation
 * @discussion - In most cases, the request is read and cached from the local database and then returned synchronously. However, due to the large information content of team members, SDK delays getting the information after login. Considering the network conditions, the SDK may not cache the information of team members timely, then the request may be an asynchronous operation with network requests (incremental request). The API will request team user profile that has not been cached locally, without triggering - (void)onUserInfoChanged: Callback.
 */
- (void)fetchTeamMutedMembers:(NSString *)teamId 
                   completion:(nullable NIMTeamMemberHandler)completion;
@end

Team information management

Edit team profile

The owner may update the team profile, and each member can only update his/her information currently. After the team profile is updated, a team notification message of team profile change (NIMSuper teamNotificationContent) will be received.

Specifically including:

Update team profile

@protocol NIMSuper teamManager <NSObject>
 * Update team profile
 *
 * @param values - Key value pair of team profile to be updated
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 * @discussion - Multiple attributes such as name and announcement of a team can be updated with The API for once. The input key-value pair is {@(NIMSuper teamUpdateTag) : NSString}. The invalid data will be filtered.
 */
- (void)updateTeamInfos:(NSDictionary<NSNumber *,NSString *> *)values
                 teamId:(NSString *)teamId
             completion:(nullable NIMTeamHandler)completion;
@end                    

Parameter List

Parameter	Type	Description
values	NSDictionary	Team information key-value pair to be updated
teamId	NSString	Team ID
completion	NIMTeamHandler	Callback after completion

Update Team Name

@protocol NIMSuper teamManager <NSObject>
/**
 * Get team name
 *
 * @param teamName - Team name
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 */
- (void)updateTeamName:(NSString *)teamName
                teamId:(NSString *)teamId
            completion:(nullable NIMTeamHandler)completion;
@end

Parameter List

Parameter	Type	Description
teamName	NSString	Team name
teamId	NSString	Team ID
completion	NIMTeamHandler	Callback after completion

Update the profile pictures of teams

@protocol NIMSuper teamManager <NSObject>
/**
 * Update profile pictures of teams
 *
 * @param teamAvatarUrl - Team avatar Url
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 */
- (void)updateTeamAvatar:(NSString *)teamAvatarUrl
                  teamId:(NSString *)teamId
              completion:(nullable NIMTeamHandler)completion;
@end

Parameter List

Parameter	Type	Description
teamAvatarUrl	NSString	Team avatar Url
teamId	NSString	Team ID
completion	NIMTeamHandler	Callback after completion

Update the team join mode

@protocol NIMSuper teamManager <NSObject>
/**
 * Update team verification mode
 *
 * @param joinMode - Verification mode
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 */
- (void)updateTeamJoinMode:(NIMTeamJoinMode)joinMode
                    teamId:(NSString *)teamId
                completion:(nullable NIMTeamHandler)completion;
@end

Parameter List

Parameter	Type	Description
joinMode	NIMTeamJoinMode	Join mode
teamId	NSString	Team ID
completion	NIMTeamHandler	Callback after completion

Update the join mode of team invitees

@protocol NIMSuper teamManager <NSObject>
/**
 * Update team verification mode for invited users
 *
 * @param joinMode - Verification mode
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 */
- (void)updateTeamBeInviteMode:(NIMTeamBeInviteMode)beInviteMode 
                        teamId:(NSString *)teamId 
                    completion:(nullable NIMTeamHandler)completion;
@end

Update team introduction

@protocol NIMSuper teamManager <NSObject>
/**
 * Update team introduction
 *
 * @param intro - Team introduction
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 */
- (void)updateTeamIntro:(NSString *)intro
                 teamId:(NSString *)teamId
             completion:(nullable NIMTeamHandler)completion;
@end

Parameter List

Parameter	Type	Description
intro	NSString	Team introduction
teamId	NSString	Team ID
completion	NIMTeamHandler	Callback after completion

Update an announcement

@protocol NIMSuper teamManager <NSObject>
/**
 * Update a team announcement
 *
 * @param announcement - Team announcement
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 */
- (void)updateTeamAnnouncement:(NSString *)announcement
                        teamId:(NSString *)teamId
                    completion:(nullable NIMTeamHandler)completion;
@end

Parameter List

Parameter	Type	Description
announcement	NSString	Team announcement
teamId	NSString	Team ID
completion	NIMTeamHandler	Callback after completion

Update team custom information

@protocol NIMSuper teamManager <NSObject>
/**
 * Update team custom information
 *
 * @param info - Team custom information
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 */
- (void)updateTeamCustomInfo:(NSString *)info
                      teamId:(NSString *)teamId
                  completion:(nullable NIMTeamHandler)completion;
@end

Parameter List

Parameter	Type	Description
info	NSString	Team custom information
teamId	NSString	Team ID
completion	NIMTeamHandler	Callback after completion

Monitor team changes

• The callback of updating teams

@protocol NIMTeamManagerDelegate <NSObject>
/**
 * A callback for updating a team
 *
 * @param team - Updated team
 */
- (void)onTeamUpdated:(NIMSuper team *)team
@end

• Team removal callback

@protocol NIMTeamManagerDelegate <NSObject>
/**
 * A callback for removing a team
 *
 * @param team - Removed team
 */
- (void)onTeamRemoved:(NIMSuper team *)team
@end

Team notifications

Team notification is a type of message ( NIMMessageTypeNotification ). After creating or joining a team, a team notification message will be issued by the CommsEase server in case of any change in a team. Like other messages, team notification messages can be fetched from the message query API provided by NIMConversationManager.

• Team notification analysis step:

  • In NIMMessage, resolve the field messageObject, and convert it into NIMSuper teamNotificationContent in a strongly typed manner.
  • In NIMSuper teamNotificationContent, resolve the field content, obtaining the superclass NIMSuper teamNotificationContent.
  • In NIMSuper teamNotificationContent, based on the field notificationType, convert the superclass NIMSuper teamNotificationContent into NIMSuper teamNotificationContent in a strongly-typed manner.

• The specific type of team notification may be resolved using the NIMSuper teamNotificationContent's operationType.

• Upon the receipt of team notification, the SDK will update the team profile cached locally, and then trigger and update the callback of delegated events.

• Team notification is a message to be received, which developers should not create or send.

Field description of team notification content NIMSuper teamNotificationContent:

• operationType: team notification event type, which indicates the type of team notification. The notification type is defined by the enum NIMSuper teamOperationType.
• source: Notification operator ID, which means the one who triggers the notification.
• targets: List of IDs of the targets notified, which means the group of users affected by the notification.
• notifyExt: extension field notified, which is defined by each operation API that triggers the notification. The field can be defined only by the server operation API currently.

For example, users removed from the team may call the server HTTP API, and input the notification extension parameters. The call will trigger a message notification of such event as users kick-out, in which case the other members who receive the message may fetch the extension field defined at kick-out by reading NIMSuper teamNotificationContent's field notifyExt.

• attachment: Some notifications are relatively complex, which require some additional information to assist the upper-level display. Team notification with additional information includes:
  • team update notification, with additional information encapsulated as NIMUpdateTeamInfoAttachment.

Set team messages Do Not Disturb

• Modify the state of mute notifications

@protocol NIMSuper teamManager <NSObject>
/**
 * Update mute status of a team
 *
 * @param state - Status of team notification
 * @param teamId - Team ID
 * @param completion - Callback that is returned after completion
 */
- (void)updateNotifyState:(NIMTeamNotifyState)state
                   inTeam:(NSString *)teamId
               completion:(nullable NIMSuper teamHandler)completion;
@end 

Parameter List

Parameter	Type	Description
state	NIMTeamNotifyState	Team notification state
teamId	NSString	Team ID
completion	NIMSuper teamHandler	Callback after completion

• Query the state of mute notifications

@protocol NIMSuper teamManager <NSObject>
/**
 * Query mute status of a team
 *
 * @param teamId - Team ID
 *
 * @return - Status of team notification
 */
- (NIMTeamNotifyState)notifyStateForNewMsg:(NSString *)teamId;
@end 

Parameter List

Parameter	Type	Description
teamId	NSString	Team ID