SuperTeam
Update time: 2023/02/09 15:59:53
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 fieldmessageObject
, and convert it intoNIMSuper teamNotificationContent
in a strongly typed manner. - In
NIMSuper teamNotificationContent
, resolve the fieldcontent
, obtaining the superclassNIMSuper teamNotificationContent
. - In
NIMSuper teamNotificationContent
, based on the fieldnotificationType
, convert the superclassNIMSuper teamNotificationContent
intoNIMSuper teamNotificationContent
in a strongly-typed manner.
- In
-
The specific type of team notification may be resolved using the
NIMSuper teamNotificationContent
'soperationType
. -
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 enumNIMSuper 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
.
- team update notification, with additional information encapsulated as
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 |