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);