Instant Messaging
Android
Getting Started
Introduction
Overview
Benefits
Features
Features
Account Integration and Login
Group Chat
Chat Room
Chat Room Tags
Multi-device Login
Statistics Monitoring
Limits
Integration
Interface Overview
Integrate and Initialize SDK
Messaging
Basic Messaging
Message History
Message Sending
Message Receiving
Recent Chats
Server Sessions
User Profile
User Relationship
Online Status Subscription
Push and Message Alert
Superteam
Chat Room
Moderation
Chat Extension
Miscellaneous Features
Best Practice
Traffic Control in Chat Rooms
Reference
API Reference
Status Codes

Group Features

Update time: 2022/06/28 17: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
/**
 * 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
// 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:

/**
 * 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:

/**
 * 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:

NIMClient.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:

// 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

// 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:

/**
 * 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:

/**
 * 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:

NIMClient.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:

// 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

/**
 * 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:

/**
 * 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:

/**
 * 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:

// 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:

// 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

// 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
/**
 * Search Team profile from the server.
 *
 * @param teamId team ID.
 * @return
 */
InvocationFuture<Team> searchTeam(String teamId);
  • Example
// 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
/**
 * 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
NIMClient.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
/**
 * 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
NIMClient.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
/**
 * 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
NIMClient.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
/**
 * 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
// 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
/**
 * 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
// 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
/**
 * 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
NIMClient.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

/**
 * 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
NIMClient.getService(TeamService.class).acceptInvite(teamId, inviter).setCallback(...);
  • Reject team invitation

  • API prototype

/**
 * 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
NIMClient.getService(TeamService.class).declineInvite(teamId, inviter, "").setCallback(callback);

Search inviters

  • API prototype
/**
 * 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
// 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
/**
 * 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
// 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
/**
 * 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
NIMClient.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.
/**
 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
NIMClient.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:

/**
 * 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):

/**
 * 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:

NIMClient.getService(TeamService.class).queryTeamMember(teamId, account).setCallback(new RequestCallbackWrapper<TeamMember>() {
    @Override
    public void onResult(int code, TeamMember member, Throwable exception) {
       ...
    }
});

Synchronous interface example:

TeamMember 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
/**
 * 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
// 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
/**
 * 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
// test is changed team profile name.
NIMClient.getService(TeamService.class).updateMyTeamNick(teamId, "test")

Modify user extension fields

  • API prototype
/**
 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
Map<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
/**
 * 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
// 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
/**
 * 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
// 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
/**
 * 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
// 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
/**
 * 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
// 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
/**
 * 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
// 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
/**
 * 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
// 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
/**
 * 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
NIMClient.getService(TeamService.class).muteAllTeamMember(teamId, true));

Querying status of muted members

  • The API returns only the list of muted members using the muteTeamMember method.
/**
 * 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
// 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
/**
 * 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.

String 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
/**
 * 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
// 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
/**
 * 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
// 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
/**
 * 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
// 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:
private 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
/**
 * 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
// 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.

Users can query ID list of specified teams.

  • API prototype
/**
 * Reversely query the team ID by team name.
 *
 * @param name team name.
 * @return team IDs.
 */
InvocationFuture<List<String>> searchTeamIdByName(String name);
  • Example
NIMClient.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:

/**
 * 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);
Was this topic helpful?
Yes
No
  • Overview
  • Creating a team
  • Getting teams
  • Getting all teams locally
  • My team count
  • Getting a specified team
  • Getting specified teams at a time
  • Getting teams of specified type
  • Getting the number of teams of specified type
  • Get a specified team from the cloud
  • Getting a team of specific type
  • Getting teams from the server
  • Dismissing a team
  • Team members management
  • Joining a team
  • Requesting membership of a team
  • Verifying requests
  • Inviting to join a team
  • Verifying invitation requests
  • Search inviters
  • Kick out team members
  • Leaving a team
  • Getting team members
  • Getting the list of team members
  • Getting a specified team member
  • Update member profiles/span>
  • Update other member profiles
  • Editing the display name in a team
  • Modify user extension fields
  • Listening for team member changes
  • Ownership transfer
  • Adding an administrator
  • Removing an administrator
  • Muting members
  • Muting a specified member
  • Muting all team members
  • Querying status of muted members
  • Team profile management
  • Editing a team profile
  • Edit a team profile
  • Edit multiple team profiles
  • Listening for team changes
  • Listening for team updates
  • Listening for removing teams
  • Team notification messages
  • Do Not Disturb setting
  • Set Do Not Disturb
  • Query Do Not Disturb status
  • Team search