Group Features
Update time: 2022/06/28 09:23:14
Overview
IM SDK provides two types of teams, ordinary team (TeamTypeEnum#Normal
) and advanced team (TeamTypeEnum#Advanced
). The advanced team has more permissions, and the APIs are consistent with ordinary operations.
- Ordinary team
Without operation authority, ordinary team applies to the scenario of quickly creating a multi-person session. Each ordinary team can only have one administrator. The administrator can add or remove members and ordinary members can add other users to the ordinary team only. New members can join the team without the consent of others members.
- Advanced team (recommended)
The advanced team is subject to more limitations on permission which is granted to the owner, the administrator, and team members. The versions earlier than v2.4.0 require invitation approval when adding a new member, but subsequent versions can set invitation mode that requires invitation approval. The advanced team covers all features of an ordinary team. Developers is recommended to create an advanced team.
Team features:
Return | Team feature | Description |
---|---|---|
String | getAnnouncement() | Get team announcement. |
long | getCreateTime() | Get team creation time. |
String | getCreator() | Get owner account. |
String | getExtension() | Get team extension configuration. |
String | getExtServer() | Get extension configuration for server. |
String | getIcon() | Get team profile picture. |
String | getId() | Get team ID. |
String | getIntroduce() | Get team introduction. |
int | getMemberCount() | Get total team member count. |
int | getMemberLimit() | Get team member limit. |
TeamMessageNotifyTypeEnum | getMessageNotifyType() | Get mute mode of team message. |
TeamAllMuteModeEnum | getMuteMode() | Get team mute mode. |
String | getName() | Get team name. |
TeamBeInvite ModeEnum |
getTeamBeInviteMode() | Get team invitation mode, approval method of invitee. |
TeamExtension UpdateModeEnum |
getTeamExtension UpdateMode() |
Get update mode of Team profile extension field, i.e. "who can update user-defined properties of team (extension field)". |
TeamInviteModeEnum | getTeamInviteMode() | Get team invitation mode, i.e. "who can invite others to the team". |
TeamUpdateModeEnum | getTeamUpdateMode() | Get Team profile update mode, i.e. "who can update team profile". |
TeamTypeEnum | getType() | Get group type. |
VerifyTypeEnum | getVerifyType() | Get verification type when the user sends a team application. |
boolean | isAllMute() | Determine that all members are muted. |
TeamAllMuteModeEnum | getMuteMode() | Get mute mode of all members. |
boolean | isMyTeam() | Determine that the user is in the team. |
void | setExtension(extension) | Set team extension configuration. |
Creating a team
CommsEase team includes ordinary team and advanced team, of which both have same message feature but different management feature. In an ordinary team, all members can invite other users and only the owner can kick out members. The advanced team has a perfect member permission system and management feature. Both teams are created using the same interface by inputting different types of parameters.
- API prototype
java/**
* Create a team.
*
* @ return InvocationFuture may set callback feature, with the parameter of the Team profile created if it succeeds.
*/
InvocationFuture<CreateTeamResult> createTeam(Map<TeamFieldEnum, Serializable> fields, TeamTypeEnum type, String postscript, List<String> members);
- Parameters
Parameter | Description |
---|---|
fields | Team preset information. "key" is data field with corresponding value. It must be consistent with fieldType defined in field. |
type | Type of team to be created. |
postscript | Invitation postscript If a temporary team is created, the parameter is invalid. |
members | List of invited member accounts. |
TeamFieldEnum
enumeration variables used in creating a team:
Enumeration | Description |
---|---|
Announcement | Team announcement. |
BeInviteMode | Team invitation mode, approval method of invitee. |
Extension | Team extension field (user-defined information at client). |
ICON | Team profile picture. |
Introduce | Team introduction. |
InviteMode | Team invitation mode, i.e. "who has a qualification to invite others into team". |
MaxMemberCount | Max. member count of specified team. MaxMemberCount cannot exceed maximum member count of app configuration. |
Name | Team name. |
TeamExtensionUpdateMode | Update mode for extension field of team profile, i.e. "who has a qualification to update user-defined properties of team (extension field)". |
TeamUpdateMode | Update mode of team profile, i.e. "who has a qualification to update team profile". |
VerifyType | Verification model of team application. |
CreateTeamResult
Description:
Parameter | Description |
---|---|
team | Returned team object after successful creation. |
failedInviteAccounts | List of invited members with team count up to limit. |
- Example
java// Team type.
TeamTypeEnum type = TeamTypeEnum.Advanced;
// Preset some related properties of a team during creation. Only the team name is valid for an ordinary team.
// in fields, "key" is a data field, "value" indicates the corresponding value, of which the type must be same as the field type defined in field.
HashMap<TeamFieldEnum, Serializable> fields = new HashMap<TeamFieldEnum, Serializable>();
fields.put(TeamFieldEnum.Name, teamName);
fields.put(TeamFieldEnum.Introduce, teamIntroduce);
fields.put(TeamFieldEnum.VerifyType, verifyType);
NIMClient.getService(TeamService.class).createTeam(fields, type, "", accounts)
.setCallback(new RequestCallback<Team> {... });
Getting teams
Getting all teams locally
Get all my teams.
- API prototype
Asynchronous interface:
java/**
* Get the list of teams you have joined.
*
* @return InvocationFuture you can set the callback feature. If successful, the parameter is the list of teams you have joined.
*/
InvocationFuture<List<Team>> queryTeamList();
Synchronous interface:
java/**
* Get the list of teams you have joined (Synchronous interface).
*
* @return list of teams you have joined.
*/
public List<Team> queryTeamListBlock();
- Example
Asynchronous request example:
javaNIMClient.getService(TeamService.class).queryTeamList().setCallback(new RequestCallback<List<Team>>() {
@Override
public void onSuccess(List<Team> teams) {
// Get the list successfully. teams are all the teams you have joined.
}
@Override
public void onFailed(int i) {
// Fail to get the list. See i parameter for specific error code.
}
@Override
public void onException(Throwable throwable) {
// Get the list abnormally.
}
});
Synchronous request example:
java// teams are all the teams you have joined.
List<Team> teams = NIMClient.getService(TeamService.class).queryTeamListBlock();
Note: The list of my teams is acquired here (if you leave or are removed from a team, the team cannot be found in the list.)
My team count
java// Get the number of teams that you join.
int queryTeamCountBlock();
Getting a specified team
If no team profile exists in local database, the interface will query in server. If you are not in the team, expired information may be returned from the interface. For the latest information, you must call searchTeam
to query in server. In addition, queryTeam interface also has Synchronous interface: queryTeamBlock.
- API prototype
Asynchronous interface:
java/**
* Search Team profile locally, or on the server if it is not available locally.
* If you are not in the team, the information returned by the interface might be expired. Please call the interface {@link #searchTeam(String)} to get the latest information.
*
* @param teamId team ID.
* @return InvocationFuture you can set the callback feature. If successful, the parameter is the team profile.
*/
InvocationFuture<Team> queryTeam(String teamId);
Synchronous interface:
java/**
* Search Team profile (only locally, instead of request on the server).
* If you are not in the team, the information returned by the interface might be expired. Please call the interface {@link #searchTeam(String)} to get the latest information.
*
* @param teamId team ID.
* @return team profile.
*/
Team queryTeamBlock(String teamId);
Note: For Synchronous interface, Team profile will be queried in local database only, instead of server.
- Example
Asynchronous interface example:
javaNIMClient.getService(TeamService.class).queryTeam(teamId).setCallback(new RequestCallbackWrapper<Team>() {
@Override
public void onResult(int code, Team t, Throwable exception) {
if (code == ResponseCode.RES_SUCCESS) {
// Successful
} else {
// Failure. See the code for error code.
}
if (exception != null) {
// Error.
}
}
});
Synchronous interface example:
java// teamId is the ID of the team to be searched.
Team team = NIMClient.getService(TeamService.class).queryTeamBlock(teamId);
Local storage for team profile:
-
When a member dismisses, leaves the team or is removed from the team, local database will still keep the Team profile and configure with invalid token. The Team profile can be queried using queryTeam, but isMyTeam will return "false". If the user manually clears all local data, in the next login and synchronization, the server will not synchronize invalid Team profile and cannot acquire information about dismissed team.
-
After team dismissal, null will be returned when information is queried in server using
searchTeam
interface.
Getting specified teams at a time
java/**
* Asynchronous interface.
* Search Team profile in batch by the team ID list.
*
* @param tidList Team ID list
* @return callback feature may be set, with the parameter of the Team profile list searched if it succeeds.
*/
InvocationFuture<java.util.List<Team>> queryTeamListById(java.util.List<java.lang.String> tidList);
/**
* Synchronous interface.
* Search Team profile in batch by the team ID list.
*
* @param tidList Team ID list.
*/
java.util.List<Team> queryTeamListByIdBlock(java.util.List<java.lang.String> tidList);
Getting teams of specified type
Get my teams by type:
- API prototype
Asynchronous interface:
java/**
* Get the list of specified team types (discussion team/advanced team) that you join.
*
* @param type team type.
* @return Callback feature may be set, with the parameter of the list of specified team types you join if it succeeds.
*/
InvocationFuture<List<Team>> queryTeamListByType(TeamTypeEnum type);
Synchronous interface:
java/**
* Get the list of specified team types (discussion team/advanced team) that you join (Asynchronous interface).
*
* @param type team type.
* @ return List of specified team types you join.
*/
public List<Team> queryTeamListByTypeBlock(TeamTypeEnum type);
- Parameters
TeamTypeEnum property | Description |
---|---|
Advanced | Advanced team, with perfect permission management feature. |
Normal | Discussion group, with basic permission management feature only. All users can join in the group and Only owner can kick out members. |
- Example
Asynchronous interface example:
java// Discussion team is taken as an example.
NIMClient.getService(TeamService.class).queryTeamListByType(TeamTypeEnum.Normal).setCallback(new RequestCallback<List<Team>>() {
@Override
public void onSuccess(List<Team> teams) {
// Success.
}
@Override
public void onFailed(int i) {
// Failure.
}
@Override
public void onException(Throwable throwable) {
// Error.
}
});
Synchronous interface example:
java// Advanced team is taken as an example.
List<Team> teams = NIMClient.getService(TeamService.class).queryTeamListByTypeBlock(TeamTypeEnum.Advanced);
Getting the number of teams of specified type
java// Get the number of specified team types you join.
int queryTeamCountByTypeBlock(TeamTypeEnum type);
Get a specified team from the cloud
Users can acquire Team profile from the server:
Getting a team of specific type
- API prototype
java/**
* Search Team profile from the server.
*
* @param teamId team ID.
* @return
*/
InvocationFuture<Team> searchTeam(String teamId);
- Example
java// teamId is the ID of the team to be searched.
NIMClient.getService(TeamService.class).searchTeam(teamId).setCallback(new RequestCallback<Team>() {
@Override
public void onSuccess(Team team) {
// Get Team profile by successful query.
}
@Override
public void onFailed(int code) {
// Failure.
}
@Override
public void onException(Throwable exception) {
// Error.
}
});
Getting teams from the server
- API prototype
java/**
* Search team profiles from the server.
*
* @param teamIdList Team ID list; take the first 10 if 10 is exceeded.
* @return
*/
InvocationFuture<TeamInfoResult> searchTeam(List<Long> teamIdList);
- Example
javaNIMClient.getService(TeamService.class).searchTeam(idList).setCallback(new RequestCallback<TeamInfoResult>() {
@Override
public void onSuccess(TeamInfoResult teaminforesult) {
onSearchTeamsInfoSuccess(teaminforesult);
}
@Override
public void onFailed(int code) {
}
@Override
public void onException(Throwable exception) {
}
});
Dismissing a team
Only team owner has the permissions.
- API prototype
java/**
* Dismiss team. Only owner has the permission to dismiss team.
*
* @param teamId team ID.
* @return InvocationFuture you can set the callback feature to listen for the operation results.
*/
InvocationFuture<Void> dismissTeam(String teamId);
- Example
javaNIMClient.getService(TeamService.class).dismissTeam(teamId).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// Dismiss team successfully.
}
@Override
public void onFailed(int code) {
// Fail to dismiss team.
}
@Override
public void onException(Throwable exception) {
// Error.
}
});
Team members management
Joining a team
Requesting membership of a team
- API prototype
java/**
* Users apply to join a team.
*
* @param tid team ID.
* @param postscript Application postscript.
* @return InvocationFuture you can set the callback feature. If successful, the parameter is the team profile.
*/
InvocationFuture<Team> applyJoinTeam(String tid, String postscript);
- Parameters
Parameter | Description |
---|---|
tid | ID of teams to which application is sent. |
postscript | Application P.S. |
- Example
javaNIMClient.getService(TeamService.class).applyJoinTeam(team.getId(), null).setCallback(new RequestCallback<Team>() {
@Override
public void onSuccess(Team team) {
// Apply for joining team with success without.
}
@Override
public void onFailed(int code) {
// Only application success, code 808.
if (code == ResponseCode.RES_TEAM_APPLY_SUCCESS) {
applyJoinButton.setEnabled(false);
ToastHelper.showToast(AdvancedTeamJoinActivity.this, R.string.team_apply_to_join_send_success);
}
// already in the team, code 809.
else if (code == ResponseCode.RES_TEAM_ALREADY_IN) {
applyJoinButton.setEnabled(false);
ToastHelper.showToast(AdvancedTeamJoinActivity.this, R.string.has_exist_in_team);
// Number of team members have reached the limit.
} else if (code == ResponseCode.RES_TEAM_LIMIT) {
applyJoinButton.setEnabled(false);
ToastHelper.showToast(AdvancedTeamJoinActivity.this, R.string.team_num_limit);
} else {
ToastHelper.showToast(AdvancedTeamJoinActivity.this, "failed, error code =" + code);
}
}
@Override
public void onException(Throwable exception) {
// Error.
}
});
- special error code
Error code | Description |
---|---|
808 | Application sent. |
809 | The user has been in the team. |
Verifying requests
After the user sends an application, all administrators will receive a system notification with the type of SystemMessageType#TeamApply
. See "System notification" for parameter description.
- Approve the application for joining
Only the administrator and team owner have the permission. If the team application is approved, all members (including the applicant) will receive a notification message.
- API prototype
java/**
* Approve user's application for joining a team.
* Only administrator and owner have the permission.
*
* @return InvocationFuture you can set the callback feature.
*/
InvocationFuture<Void> passApply(String teamId, String account);
- Parameters
Parameter | Description |
---|---|
teamId | Team ID. |
account | Applicant ID. |
- Example
java// teamId is the ID of the team which a user applies for join; account is the ID of the user who makes the application.
NIMClient.getService(TeamService.class).passApply(teamId, account).setCallback(...);
- Reject the application for joining
Only the administrator and team owner have the permission. If the team application is rejected, the applicant will receive a system notification with the type of SystemMessageType#RejectTeamApply
. See "System notification" for parameter description. If any administrator executes operation, other administrators cannot repeat the operation.
- API prototype
java/**
* Reject the user's application for joining a team.
* Only administrator and owner have the permission.
*
* @return InvocationFuture you can set the callback feature
*/
InvocationFuture<Void> rejectApply(String teamId, String account, String reason);
- Parameters
Parameter | Description |
---|---|
teamId | Team ID. |
account | Applicant ID. |
reason | Disapproval reason, optional. |
- Example
java// teamId is the ID of the team which a user applies for join; account is the ID of the user who makes the application.
NIMClient.getService(TeamService.class).rejectApply(teamId, account, "You have been rejected").setCallback(...);
Inviting to join a team
All members in an ordinary team can invite other uses to the team. In early versions before SDK 2.4.0, advanced team allows administrator and owner to invite users only. In SDK 2.4.0 and subsequent versions, advanced team can set invitation mode when being created, and allows administrator or all members to invite other users. If the number of teams in which invitees have joined reaches the limit, then their accounts will be returned.
- API prototype
java/**
* Add members and set custom field.
*
* @return InvocationFuture you can set the callback feature to listen for the operation results.
*/
InvocationFuture<List<String>> addMembersEx(String teamId, List<String> accounts, String msg, String customInfo);
- Parameters
Parameter | Description |
---|---|
teamId | Team ID. |
accounts | List of member accounts to be added to team. |
msg | Invitation postscript. It can be set to null if necessary. |
customInfo | User-defined extension field. It can be set to null if necessary. |
- Example
javaNIMClient.getService(TeamService.class).addMembersEx(teamId, accounts, "You are invited to the team")
.setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// Return onSuccess, which indicates that invitation does not need the other party's consent, and the other party has joined the team successfully.
}
@Override
public void onFailed(int code) {
// Return onFailed, with the return code of 810, which indicates that invitation has been made successfully, but the other's consent is required.
}
@Override
public void onException(Throwable exception) {
...
}
});
Verifying invitation requests
The invited users will receive a system message SystemMessage with type SystemMessageType#TeamInvite
. Only when accepting invitation, the user can be added to the team.
The user can accept or reject the team invitation. After accepting the invitation, the user can indeed join the team. If the team application is rejected, the applicant will receive a system notification with type SystemMessageType#DeclineTeamInvite
.
-
Accept team invitation
-
API prototype
java/**
* Accept invitations to join in a team.
*
* @return InvocationFuture you can set the callback feature.
*/
InvocationFuture<Void> acceptInvite(String teamId, String inviter);
- Parameters
Parameter | Description |
---|---|
teamId | Team ID. |
inviter | The account of an inviter. |
- Example
javaNIMClient.getService(TeamService.class).acceptInvite(teamId, inviter).setCallback(...);
-
Reject team invitation
-
API prototype
java/**
* Notice of rejecting someone's invitation to join in a team.
*
* @return InvocationFuture you can set the callback feature.
*/
InvocationFuture<Void> declineInvite(String teamId, String inviter, String reason);
- Parameters
Parameter | Description |
---|---|
teamId | Team ID. |
inviter | The account of an inviter. |
reason | Disapproval reason, optional. |
- Example
javaNIMClient.getService(TeamService.class).declineInvite(teamId, inviter, "").setCallback(callback);
Search inviters
- API prototype
java/**
* Get the inviter of new members ("Null" indicates active joining, without inviter).
*
* @param tid
* @param accids Search user accid list, up to 200.
* @return return the corresponding relationships of users, key is the inviteAccid of accid value.
*/
InvocationFuture<Map<String, String>> getMemberInvitor(String tid,List<String> accids);
- Example
java// accids indicates the list of members searched.
NIMClient.getService(TeamService.class).getMemberInvitor(tid, accids).setCallback(
new RequestCallbackWrapper<Map<String, String>>() {
@Override
public void onResult(int code, Map<String, String> result, Throwable exception) {
// result is the corresponding relationship.
}
});
Kick out team members
In ordinary teams, only the owner can kick out members. In advanced team, owner and administrator can kick out members, and the administrator cannot kick out owner and other administrators. After the kick-out, all team members (including kicked out member) will receive a notification message IMMessage with type NotificationType#KickMember
and attachment type MemberChangeAttachment
.
- API prototype
java/**
* Remove members; only the creater has the permission.
*
* @return InvocationFuture you can set the callback feature to listen for the operation results.
*/
InvocationFuture<java.lang.Void> removeMembers(java.lang.String teamId, java.util.List<java.lang.String> members);
- Parameters
Parameter | Description |
---|---|
teamId | Team ID. |
members | Account list of kicked out members. |
- Example
java// teamId indicates team ID, and account is account of the kicked member.
NIMClient.getService(TeamService.class).removeMembers(teamId, accountList).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// Success.
}
@Override
public void onFailed(int code) {
// Failure.
}
@Override
public void onException(Throwable exception) {
// Error.
}
});
Leaving a team
The owner of ordinary team can leave the team. If the owner leaves, then there is no owner in the team. In advanced team, except owner (changing owner ), other members can leave the team. When a member leaves the team, all members (including the leaver) will receive a notification message IMMessage with attachment type MemberChangeAttachment
.
- API prototype
java/**
* Quit a team.
*
* @param teamId team ID.
* @return InvocationFuture you can set the callback feature to listen for the operation results.
*/
InvocationFuture<Void> quitTeam(String teamId);
- Example
javaNIMClient.getService(TeamService.class).quitTeam(teamId).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// Quit a team successfully.
}
@Override
public void onFailed(int code) {
// Fail to quit a team.
}
@Override
public void onException(Throwable exception) {
// Error.
}
});
Getting team members
The data of team members is large, and the list of team members is not required except for joining the corresponding interface. Therefore, SDK will not synchronize the data of team members on login, but determine that synchronization is required based on the principle of capture on demand when the upper layer actively calls to acquire the list of members in specified team.
SDK local storage for team member profile: When a member leaves the team or is removed from the team, local database will keep his information and configure with invalid token. The information about this member can be queried using queryTeamMember, but isInTeam will return "false".
TeamMember:
Return | TeamMember property | Description |
---|---|---|
String | getAccount() | Team member account. |
Map | getExtension() | Get the extension field. |
String | getInvitorAccid() | Get team inviter. Null indicates that the user joins a team. |
long | getJoinTime() | Get join time of members. |
String | getTeamNick() | Get user display name in the team. |
String | getTid() | Get team ID. |
TeamMemberType | getType() | Team member type. |
boolean | isInTeam() | Determine that the user is in the team. |
boolean | isMute() | : It determines whether a user is muted. |
Getting the list of team members
- Get all team members.
java/**
Get the list of team member profile of specified team.<br>
* You may just read the cached data from the local database, or synchronize the new data from the server, so it may take a long time.
*
* @param teamId team ID.
* @return InvocationFuture you can set the callback feature. If successful, the parameter is the team member profile list.
*/
InvocationFuture<List<TeamMember>> queryMemberList(String teamId);
- Example
javaNIMClient.getService(TeamService.class).queryMemberList(teamId).setCallback(new RequestCallbackWrapper<List<TeamMember>>() {
@Override
public void onResult(int code, final List<TeamMember> members, Throwable exception) {
...
}
});
Getting a specified team member
- Get team members by team ID and user account.
If information about local team member is expired, SDK will acquire the latest information from the server.
- API prototype
Asynchronous interface:
java/**
* Query the team member profile If the local team member profile has expired, please go to the server to get the latest information.
*
* @param teamId team ID.
* @param account team member account.
* @return InvocationFuture you can set the callback feature. If successful, the parameter is the team member profile.
*/
InvocationFuture<TeamMember> queryTeamMember(String teamId, String account);
Synchronous interface (for querying local Team profile only):
java/**
* Query the team member profile (Synchronous edition) Only query local team profile.
*
* @param teamId team ID.
* @param account team member account.
* @return team member profile.
*/
TeamMember queryTeamMemberBlock(String teamId, String account);
- Example
Asynchronous interface example:
javaNIMClient.getService(TeamService.class).queryTeamMember(teamId, account).setCallback(new RequestCallbackWrapper<TeamMember>() {
@Override
public void onResult(int code, TeamMember member, Throwable exception) {
...
}
});
Synchronous interface example:
javaTeamMember member = NIMClient.getService(TeamService.class).queryTeamMemberBlock(teamId, account);
Update member profiles/span>
Update other member profiles
The member display name of the ordinary team cannot be updated.
For advanced team, the team owner can update profile names of all team members. The administrator can only update the profile names of ordinary members in the team.
- API prototype
java/**
* The team administrator can change the profile names of other members in the team.
* Only team administrator and owner have the permission.
*
* @param teamId team ID.
* @param account to-be-changed team member account.
* @param nick New team profile name.
* @return InvocationFuture you can set the callback feature to listen for the operation results.
*/
InvocationFuture<Void> updateMemberNick(String teamId, String account, String nick);
- Example
java// teamId represents the ID of a team, account indicates the team member account to be updated, display name indicates the new team profile name
NIMClient.getService(TeamService.class).updateMemberNick(teamId, account, profile name).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// Successful
}
@Override
public void onFailed(int code) {
// Failed
}
@Override
public void onException(Throwable exception) {
// Error
}
});
Editing the display name in a team
- API prototype
java/**
* Change own team profile name.
*
* @param teamId team ID.
* @param nick New team profile name.
* @return InvocationFuture you can set the callback feature to listen for the operation results.
*/
InvocationFuture<Void> updateMyTeamNick(String teamId, String nick);
- Example
java// test is changed team profile name.
NIMClient.getService(TeamService.class).updateMyTeamNick(teamId, "test")
Modify user extension fields
- API prototype
java/**
Update users' own extension field in team (custom property).
*
* @param teamId team ID.
* @param extension new extension field (user-defined attribute).
* @return InvocationFuture you can set the callback feature to listen for the operation results.
*/
InvocationFuture<Void> updateMyMemberExtension(String teamId, Map<String, Object> extension);
- Example
javaMap<String, Object> extension = new HashMap<>();
extension.put("ext","newExt");
NIMClient.getService(TeamService.class).updateMyMemberExtension(teamId, ext)
Listening for team member changes
The inter-process asynchronous call is required for acquiring team member profile, so that developers must cache the information in the third-party APP, and then access local cache to query team member profile. SDK can inform registered observer of any change in team member profile. At this time, the third-party app can update cache and refresh the interface.
- listen for change of team member profile
java/**
* Observer notification of changing team member profile.
* If the upper-level app manages the cache of team profile, the cache may be updated using the interface.
* @param observer, the parameter is the list of updated team member profile.
* @param register true indicates registered, and true indicates unregistered.
*/
public void observeMemberUpdate(Observer<List<TeamMember>> observer, boolean register);
- Example
java// Observer notification of changing team member profile New members are added to the team, and you will receive this notification in case of change in member profile.
// The returned parameter is the list of updated team member profile.
Observer<List<TeamMember>> memberUpdateObserver = new Observer<List<TeamMember>>() {
@Override
public void onEvent(List<TeamMember> members) {
}
};
// Register or unregister the observer.
NIMClient.getService(TeamServiceObserver.class).observeMemberUpdate(memberUpdateObserver, register);
- listen for change of removing team members
java/**
* Observer notification of removing team member.
* @param observer, parameter is the removed group member.
* @param register true indicates registered, and true indicates unregistered.
*/
public void observeMemberRemove(Observer<TeamMember> observer, boolean register);
- Example
java// Observer notification of removing team member.
private Observer<TeamMember> memberRemoveObserver = new Observer<TeamMember>() {
@Override
public void onEvent(TeamMember member) {
}
};
// Register or unregister the observer
NIMClient.getService(TeamServiceObserver.class).observeMemberRemove(memberRemoveObserver, register);
Ownership transfer
The advanced team owner can transfer the ownership to other team members, so that the member with the ownership becomes new owner and original owner will become an ordinary member. The original team owner can also leave the team when transferring permission.
- API prototype
java/**
* Owner transfers the owner permission to another member, and the another member will become the owner after the transfer.
* The original owner will become an ordinary member. Where the quit parameter is true, the original owner will quit the team.
*
* @return InvocationFuture may set callback feature, with the parameter of quit value if it succeeds;
* quit: false: the parameter only covers the original owner and the current owner (i.e. operator and account). The permissions have been updated.
* quit is true: Parameter is null.
*/
InvocationFuture<List<TeamMember>> transferTeam(String tid, String account, boolean quit);
- Parameters
Parameter | Description |
---|---|
tid | Team ID. |
account | Account of new team owner. |
quit | Determine whether to quit the team when transferring permissions. |
- Example
java// false indicates the owner does not quit the team after the transfer.
NIMClient.getService(TeamService.class).transferTeam(teamId, account, false)
.setCallback(new RequestCallback<List<TeamMember>>() {
@Override
public void onSuccess(List<TeamMember> members) {
// Team owner has been successfully changed.
}
@Override
public void onFailed(int code) {
// Fail to change team owner.
}
@Override
public void onException(Throwable exception) {
// Error.
}
});
Adding an administrator
In an advanced team, the owner can Add an administrator. After the operation is executed, all members will receive a notification message IMMessage with the attachment type of MemberChangeAttachment
.
- API prototype
java/**
* Owner adds administrator.
* Only owner has the permission.
*
* @param teamId team ID.
* @param accounts list of user accounts in which the owner will become an administrator.
* @return InvocationFuture you can set the callback feature. If successful, the parameter is the new team administrator list.
*/
InvocationFuture<List<TeamMember>> addadministrators(String teamId, List<String> accounts);
- Parameters
Parameter | Description |
---|---|
teamId | Team ID. |
accounts | Account list of users to be promoted as administrators. |
InvocationFuture | The invocation feature can be configured. If it is successful, the parameter will be list of promoted team members (permissions have been promoted to administrator level). |
- Example
java// teamId is the ID of the team subject to operation, accountList indicates the account list of users to be promoted as administrators.
NIMClient.getService(TeamService.class).addadministrators(teamId, accountList).setCallback(new RequestCallback<List<TeamMember>>() {
@Override
public void onSuccess(List<TeamMember> administrators) {
// Add the team administrator successfully added.
}
@Override
public void onFailed(int code) {
// Fail to add the team administrator.
}
@Override
public void onException(Throwable exception) {
// Error.
});
Removing an administrator
In an advanced team, the owner can remove administrator. After the operation is executed, all members will receive a notification message IMMessage with the attachment type of MemberChangeAttachment
.
- API prototype
java/**
* Owner recalls administrator permissions.
* Only owner has the permission.
*
* @param teamId team ID.
* @param administrators accounts list of accounts in which the administrator will be recalld.
* @return InvocationFuture you can set the callback feature. If successful, the parameter is the list of recalld team members (privileges become normal).
*/
InvocationFuture<List<TeamMember>> removeadministrators(String teamId, List<String> administrators);
- Parameters
Parameter | Description |
---|---|
teamId | Team ID. |
administrators | Account list of administrators to be dismissed. |
InvocationFuture | The invocation feature can be configured. If it is successful, the parameter will be list of dismissed team members (permissions have been declined to Normal level). |
- Example
java// teamid is the team ID, accountList is the account list of administrators to be recalld.
NIMClient.getService(TeamService.class).removeadministrators(teamId, accountList).setCallback(new RequestCallback<List<TeamMember>>() {
@Override
public void onSuccess(List<TeamMember> members) {
// Remove the team administrator successfully.
}
@Override
public void onFailed(int code) {
// Fail to remove the team administrator.
}
@Override
public void onException(Throwable exception) {
// Error
}
});
Muting members
Muting a specified member
- API prototype
java/**
* Mute or unmute a member.
*
* @return InvocationFuture You can set the callback function to listen for the operation result.
*/
InvocationFuture<Void> muteTeamMember(String teamId, String account, boolean mute);
- Parameters
Parameter | Description |
---|---|
teamId | Team ID. |
account | Muted; unmuted account. |
mute | true: to mute. false: to unmute. |
- Example
java// Take mute operation as an example.
NIMClient.getService(TeamService.class).muteTeamMember(teamId, account, true).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// Success.
}
@Override
public void onFailed(int code) {
// Failure.
}
@Override
public void onException(Throwable exception) {
// Error.
}
});
Muting all team members
Mute all the team members. Only the owner or administrator has the permissions. The team update interface will be invoked after successful mute.
- API prototype
java/**
* Mute and unmute the team, effective for ordinary members, only team owner and administrator have this permission.
*
* @param teamId team ID.
* @param accountList list of muted and unmuted accounts.
* @return InvocationFuture you can set the callback feature to listen for the operation results.
*/
InvocationFuture<Void> muteAllTeamMember(String teamId, boolean mute);
- Parameters
Parameter | Description |
---|---|
teamId | Team ID |
mute | true: to mute. false: to unmute. |
- Example
javaNIMClient.getService(TeamService.class).muteAllTeamMember(teamId, true));
Querying status of muted members
- The API returns only the list of muted members using the muteTeamMember method.
java/**
* Query the list of muted team members.
* The operation only returns the users muted by calling TeamService#muteTeamMember(String, String, boolean).
*
* @param teamId Team ID.
* @return team member profile list.
*/
List<TeamMember> queryMutedTeamMembers(String teamId);
- Example
java// members mean the list of members muted.
List<TeamMember> members = NIMClient.getService(TeamService.class).queryMutedTeamMembers(teamId);
- Query global mute status
The corresponding status can be acquired using Team#getMuteMode
and Team#isAllMute
.
- Query that a user is muted by "muteTeamMember " method.
It can be acquired using TeamMember - isMute()
.
Note: If global mute occurs, but the user is not muted by "muteTeamMember" method, then TeamMember - isMute()
is still "false".
Team profile management
Editing a team profile
See following TeamFieldEnum
for editable attributes. Note that the extension field of team server Ext_Server_Only
can be updated at server client only.
TeamFieldEnum attribute | Description | Data type |
---|---|---|
AllMute | All mute (mute for all members). The field is "Read Only". It is invalid to update the field using "Update team profile" interface. | TeamAllMuteModeEnum |
Announcement | Team announcement | String |
BeInviteMode | Team invitation mode, approval method of invitee | TeamBeInviteModeEnum |
Ext_Server_Only | Team extension field (updated at server only) | String |
Extension | Team extension field (user-defined information at client) | String |
ICON | Team profile picture | String |
Introduce | Team introduction | String |
InviteMode | Team invitation mode, i.e. "who has a qualification to invite others into team". | TeamInviteModeEnum |
Name | Team name | String |
TeamExtensionUpdateMode | Update mode for extension field of team profile, i.e. "who has a qualification to update user-defined properties of team (extension field)". |
TeamExtensionUpdateModeEnum |
TeamUpdateMode | Update mode of team profile, i.e. "who has a qualification to update team profile". | TeamUpdateModeEnum |
undefined | Undefined domain | |
VerifyType | Verification model of team application | VerifyTypeEnum |
MaxMemberCount | Max. member count of specified team | int |
-
For uploading a teamprofile picture to CommsEase server, see profile picture processing.
-
After modification, all members will receive a notification message IMMessage with attachment type
UpdateTeamAttachment
. If the observer for Team profile change is registered, the observer will also receive notification. See "listen for team change".
Edit a team profile
- API prototype
java/**
* Update team profile.
*
* @return InvocationFuture you can set the callback feature to listen for the operation results.
*/
InvocationFuture<Void> updateTeam(String teamId, TeamFieldEnum field, Serializable value);
- Parameters
Parameter | Description |
---|---|
teamId | Team ID. |
field | Domain to be updated. |
value | New value of domain to be updated. The value type must be consistent with fieldType defined in field. |
- Example
The team announcement is taken for an example.
javaString announcement = "This is the updated team announcement";
NIMClient.getService(TeamService.class).updateTeam(teamId, TeamFieldEnum.Announcement, announcement).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// Success.
}
@Override
public void onFailed(int code) {
// Failure.
}
@Override
public void onException(Throwable exception) {
// Error.
}
});
Edit multiple team profiles
- API prototype
java/**
* Team profile is updated at a time, and the values of multiple fields can be updated at one time.
*
* @return InvocationFuture you can set the callback feature to listen for the operation results.
*/
InvocationFuture<Void> updateTeamFields(String teamId, Map<TeamFieldEnum, Serializable> fields);
- Parameters
Parameter | Description |
---|---|
teamId | Team ID |
fields | New information about all fields to be updated. The value type must be consistent with fieldType defined in field. |
- Example
java// Take the name, introduction, and announcement as examples.
Map<TeamFieldEnum, Serializable> fieldsMap = new HashMap<>();
fieldsMap.put(TeamFieldEnum.Name, "new name");
fieldsMap.put(TeamFieldEnum.Introduce, "new introduction");
fieldsMap.put(TeamFieldEnum.Announcement, "new announcement");
NIMClient.getService(TeamService.class).updateTeamFields(teamId,
fieldsMap).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void aVoid) {
// Success.
}
@Override
public void onFailed(int i) {
// Failure.
}
@Override
public void onException(Throwable throwable) {
// Error.
}
});
Listening for team changes
The inter-process asynchronous call is required for acquiring team profile, so that developers must cache Team profile in the third-party APP, and then access local cache to query team profile. SDK can inform registered observer of any change in team profile. At this time, the third-party app can update cache and refresh the interface.
Listening for team updates
- API prototype
java/**
* Observer notification of changing Team profile Notifications of creating and updating the team are delivered through this interface.
* @param observer, the parameter is the list of updated team profile.
* @param register true indicates registered, and true indicates unregistered.
*/
public void observeTeamUpdate(Observer<List<Team>> observer, boolean register);
- Example
java// Create Team profile change observer.
Observer<List<Team>> teamUpdateObserver = new Observer<List<Team>>() {
@Override
public void onEvent(List<Team> teams) {
}
};
// Register or unregister the observer.
NIMClient.getService(TeamServiceObserver.class).observeTeamUpdate(teamUpdateObserver, register);
Listening for removing teams
After successful operation, Team#isMyTeam will return "false".
- API prototype
java/**
* Observer notification of removing team This notification will be received when you quit a team, or when the team is dismissed, or when you are kicked out of the team.
* @param observer, The isMyTeam interface of the team returns false when the parameter is the removed team profile.
* @param register true indicates registered, and true indicates unregistered.
*/
public void observeTeamRemove(Observer<Team> observer, boolean register);
- Example
java// Create the observer of removing the team. This notification will be received when you quit a team, or when you are kicked out of the team, or when the team is dismissed.
Observer<Team> teamRemoveObserver = new Observer<Team>() {
@Override
public void onEvent(Team team) {
// Since the interface may still need to display information such as the team name, the Team object will be returned in the parameters.
// The isMyTeam interface of this object returns false.
}
};
// Register or unregister the observer.
NIMClient.getService(TeamServiceObserver.class).observeTeamRemove(teamRemoveObserver, register);
Team notification messages
The message type of team notification is MsgTypeEnum.notification
. When the user is added to team successfully, for any change about the team (including the operation of joining in team independently), CommsEase server will send a team notification.
Events triggering team notification message currently include:
NotificationType enumeration | Attachment type | Event description |
---|---|---|
AcceptInvite | MemberChangeAttachment | Add members into team after approval for invitation (a mode requiring approval of invitee). |
InviteMember | MemberChangeAttachment | Invite members into a team (a mode not requiring approval of invitee). |
AddTeamadministrator | MemberChangeAttachment | Add an administrator. |
KickMember | MemberChangeAttachment | Kick out of team. |
TransferOwner | MemberChangeAttachment | Transfer owner. |
PassTeamApply | MemberChangeAttachment | Successfully join a team. |
RemoveTeamadministrator | MemberChangeAttachment | Remove administrator. |
DismissTeam | DismissAttachment | Dismiss team. |
LeaveTeam | LeaveTeamAttachment | Leave team. |
MuteTeamMember | MuteMemberAttachment | Team mute/unmute. |
UpdateTeam | UpdateTeamAttachment | Team profile update. |
Team notification analysis step:
- Get message type using IMMessage.getMsgType(). If the type is MsgTypeEnum.notification, then it is a notification message.
- Transform strong type of attachment object acquired using IMMessage.getAttachment() into NotificationAttachment.
- Get detailed NotificationType using NotificationAttachment.getType().
- Transform strong type of attachment acquired using IMMessage.getAttachment() into corresponding attachment type based on corresponding NotificationType (see above Table).
Considerations:
- For MemberChangeAttachment, the event recipient can be acquired using getTargets(). If B is kicked out of the team, then the account of B can be acquired using getTargets().
- For MuteMemberAttachment, it is a sub-type of MemberChangeAttachment, the event recipient can be acquired using getTargets(), and the team can be muted or unmuted using isMute().
- For UpdateTeamAttachment, you should analyze updated team profile. It is same type for the global mute. See Demo sample code:
javaprivate static String buildUpdateTeamNotification(String tid, String account, UpdateTeamAttachment a) {
StringBuilder sb = new StringBuilder();
// Start parsing
for (Map.Entry<TeamFieldEnum, Object> field : a.getUpdatedFields().entrySet()) {
if (field.getKey() == TeamFieldEnum.Name) {
sb.append("name updated to " + field.getValue());
} else if (field.getKey() == TeamFieldEnum.Introduce) {
sb.append("team introduction updated to " + field.getValue());
} else if (field.getKey() == TeamFieldEnum.Announcement) {
sb.append(TeamHelper.getTeamMemberDisplayNameYou(tid, account) + " team announcement updated");
} else if (field.getKey() == TeamFieldEnum.VerifyType) {
VerifyTypeEnum type = (VerifyTypeEnum) field.getValue();
String authen = "team authentication permission updated to";
if (type == VerifyTypeEnum.Free) {
sb.append(authen + NimUIKit.getContext().getString(R.string.team_allow_anyone_join));
} else if (type == VerifyTypeEnum.Apply) {
sb.append(authen + NimUIKit.getContext().getString(R.string.team_need_authentication));
} else {
sb.append(authen + NimUIKit.getContext().getString(R.string.team_not_allow_anyone_join));
}
} else if (field.getKey() == TeamFieldEnum.Extension) {
sb.append("team extension field updated to " + field.getValue());
} else if (field.getKey() == TeamFieldEnum.Ext_Server_Only) {
sb.append("team extension field (server) updated to " + field.getValue());
} else if (field.getKey() == TeamFieldEnum.ICON) {
sb.append("Teamprofile picture updated");
} else if (field.getKey() == TeamFieldEnum.InviteMode) {
Sb.append("invitation permission updated to" + field.getValue());
} else if (field.getKey() == TeamFieldEnum.TeamUpdateMode) {
sb.append("Team profile modification permission updated to " + field.getValue());
} else if (field.getKey() == TeamFieldEnum.BeInviteMode) {
sb.append("invitee authentication permission updated to " + field.getValue());
} else if (field.getKey() == TeamFieldEnum.TeamExtensionUpdateMode) {
sb.append("Team extension field modification permission updated to " + field.getValue());
} else if (field.getKey() == TeamFieldEnum.AllMute) {
TeamAllMuteModeEnum teamAllMuteModeEnum = (TeamAllMuteModeEnum) field.getValue();
if (teamAllMuteModeEnum == TeamAllMuteModeEnum.Cancel) {
sb.append("Unmute all team members");
} else {
sb.append("Mute all team members");
}
} else {
sb.append("team" + field.getKey() + "updated to" + field.getValue());
}
sb.append("\r\n");
}
if (sb.length() < 2) {
return "unknown notification";
}
return sb.delete(sb.length() - 2, sb.length()).toString();
}
Do Not Disturb setting
A team can be set with message and notification tip mode. The team message and notification tip includes:
- All reminded (default).
- Message remind from owner or administrator only.
- All not reminded.
The above notification tip refers to Push and message alert in CommsEase system.
Set Do Not Disturb
- API prototype
java/**
* Set specified type of team message notification, multi-client sync supported.
*
* @param teamId Team ID.
* @param notifyType Notification type enum.
* @return InvocationFuture you can set the callback feature to listen for the operation results.
*/
InvocationFuture<Void> muteTeam(String teamId, TeamMessageNotifyTypeEnum notifyType);
- Parameters
Parameter | Description |
---|---|
teamId | Team ID |
TeamMessageNotifyTypeEnum | The message alert type enumeration includes "all reminded", "message alert from administrator only", and "all not reminded". |
- Example
java// set "reminded by administrator only".
TeamMessageNotifyTypeEnum type = TeamMessageNotifyTypeEnum.administrator;
NIMClient.getService(TeamService.class).muteTeam(teamId, type).setCallback(new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
// Success.
}
@Override
public void onFailed(int code) {
// Failure.
}
@Override
public void onException(Throwable exception) {
// Error.
}
});
Query Do Not Disturb status
The message notification tip mode of corresponding team can be acquired using getMessageNotifyType
interface of Team
from the local database.
Team search
Users can query ID list of specified teams.
- API prototype
java/**
* Reversely query the team ID by team name.
*
* @param name team name.
* @return team IDs.
*/
InvocationFuture<List<String>> searchTeamIdByName(String name);
- Example
javaNIMClient.getService(TeamService.class).searchTeamIdByName("Android").setCallback(new RequestCallbackWrapper<List<String>>() {
@Override
public void onResult(int code, List<String> result, Throwable exception) {
if (code == ResponseCode.RES_SUCCESS) {
// Success.
} else {
// Failure. See the code for error code.
}
if (exception != null) {
// Error.
}
}
});
Users can search all teams with matched keywords from the local client:
java/**
* Reversely query the team ID by team name.
*
* @param name Team name.
* @return Team IDs.
*/
InvocationFuture<java.util.List<Team>> searchTeamsByKeyword(java.lang.String keyword);