NIM SDK allows you to manage advanced groups, such as creating, joining, and leaving groups, transferring the ownership of a group, querying group information, and dismissing a group.

How it works

The TeamService interface provides group operations and the observer for notifications when specific event occurs.

Listeners for group events

You can register listeners for group events before group operations. If listeners are registered, you can receive notifications for corresponding group operations.

Register the following observers for corresponding operations or events:

• onTeamListRemove: Listen to the event of deleting a group. Notifications are sent when you leave a group, or are removed from a group or a group is dismissed.
• onTeamListUpdate: Listen to the event of updating group information. Notifications are sent when group information is updated.

Sample code:

  //// Observer for updating the information about a group. A notification will be sent when a new group is created or the profile of a group is updated.
  /// observer The observer. The parameter is the list of group whose profiles are updated.
  final result = await NimCore.instance.teamService.onTeamListUpdate.listen((event) {
          print('=======onTeamListUpdate event : $event');
        });

 /// Observer for deleting a group. A notification will be sent when a user leave a group, or a group is dismissed, or a user is removed from a group.
 /// observer The observer. The parameter is the group information to be removed.
 /// If a group is deleted, Team#isMyTeam returns false
   final result = await NimCore.instance.teamService.onTeamListRemove.listen((event) {
          print('=======onTeamListRemove event : $event');
        });

Since obtaining group profile and group member information requires cross-process asynchronous calls, your app can store the group member information in the cache and access the group member information from the local cache when querying group member information. When the group or group member information changes, the SDK will notify the registered observers. At this time, your app can update the cache and refresh the interface.

Workflow

This document introduces the implementation process of group management by taking the interaction among group owners, administrators, and regular members.

Create a group

Create a group by calling the createTeam method and the creator becomes the group owner.

Parameters:

Parameter	Description
CreateTeamOptions	Default group information, For more information, see NIMCreateTeamOptions
members	list of members to be invited

• For more information about the default group attributes, see Group.
• After a group is successfully created, return the team object and the list of members (failedInviteAccounts) whose groups they have joined have reached the upper limit.

** Sample code:**

// Group type
    NIMTeamTypeEnum type = NIMTeamTypeEnum.advanced;
// Some related attributes of the group can be preset.
In fields, the key is the data field,  and value is the want to corresponding value. The value type must be the same as the fieldType defined in the field
    NIMCreateTeamOptions  options= NIMCreateTeamOptions();
    final result = await NimCore.instance.teamService.createTeam(
        createTeamOptions: options,
        members: ['members']);

Join a group

You can join a group using the following methods:

• Accepts the invitation to join a group.
• Request to join a group

Invite users to join a group

The permission to invite to the group can be defined by inviteMode. Set the value to manager (default), only the group owner and administrator can invite people to join a group. Set the value to all, everyone in the group can invite people to join the group.

Invite users to join a group by calling the addMembersEx method.

• If the invitation mode beInviteMode of the group is noAuth, users can join the group without verification.
• If the invitation mode beInviteMode of the group is needAuth(default) the invited user must agree to join the group.

If an invited member has reached the upper limit of joined groups, the accounts failing to join the group are returned.

Parameters:

Parameter	Description
teamId	group ID
account	Account to be invited.
customInfo	Custom extension field. Ignore the extension if not required. The field can contain up to 512 characters.
msg	additional message for invitation. Ignore it if not required.

• After the invitation is sent, the invited user will receive a SystemMessage system notification of teamInvite type.
• The invited user can call acceptInvite method to accept the invitation to join the group. The user joins the group once accepting the invitation. All group members will receive a notification of MsgTypeEnum.notification and the trigger event is acceptInvite.
• The invited user can also call the declineInvite method to reject the invitation. If the invitation is rejected, the inviter receives a SystemMessage system notification of declineTeamInvite type.

** Sample code:**

   final result = await NimCore.instance.teamService.addMembersEx(
      teamId: teamId,
      accounts: [accid1,accid2],
      msg: 'message',
      customInfo: 'message',
    );

// Accept the invitation
    final result = await NimCore.instance.teamService.acceptInvite(
      teamId,
      inviter,
    );

// Reject the invitation
    final result = await NimCore.instance.teamService.declineInvite(
      teamId,
      inviter,
        reason
    );

Request to join a group

You can request to join a group by calling the applyJoinTeam method.

• If the verifyType of the group is free, users can join the group without verification.
• If the join mode verifyType of the group is apply, the group owner or group administrator is required to approve the request.
• If the group's join mode verifyType is private, the group does not accept requests. Users can only join the group by invitation.

Group information is returned when a user requests to join a group or waits for request verification..

Parameters:

Parameter	Description
teamId	group ID
postscript	additional message

• If you send a join request, the group owner and administrators receive a SystemMessage system notification of applyJoinTeam type.
• The group owner and administrators can approve the request by calling passApply. All group members will receive a notification of NIMMessageType.notification and the trigger event is passTeamApply.
• The group owner and group administrators can also call the rejectApply method to reject the request. If the request is rejected, the requester receives a SystemMessage system notification of rejectTeamApply type.

** Sample code:**

  final result = await NimCore.instance.teamService.applyJoinTeam(
      'teamId',
      'postscript',
    );

// Approve the request
    final result = await NimCore.instance.teamService.passApply(
      'teamId',
      'account'
    );

// Reject the request
    final result = await NimCore.instance.teamService.rejectApply(
      'teamId',
      'account',
      'reason'
    );

Transfer the ownership of a group

Only the group owner have the permission to transfer the ownership of a group.

The group owner can transfer the ownership of a group by calling transferTeam.

• After the ownership of the group is transferred. All group members will receive a notification of NIMMessageType.notification and the trigger event is transferOwner.
• If the group owner leaves the group while transferring the ownership, call quitTeam to leave the group. All group members will receive a notification of NIMMessageType.notification and the trigger event is leaveTeam.

Parameters:

Parameter	Description
teamId	Group ID
account	Account of the new owner
quit	Whether to leave the group while transferring the group true: leave the group. false: do not leave the group and the role becomes a regular group member

** Sample code:**

// false: the group owner will not leave the group after transfer
 final result = await NimCore.instance.teamService.transferTeam(
      'teamId',
      'account',
      false,
    );

Leave a group

You can leave a group using the following methods:

• You are removed by the group owner or group administrator.
• You leave the group.

Remove a member from a group

• Only the owner and moderators can remove members from the group.
• Administrators cannot remove group owners or other administrators from a group.

You can remove a group member by calling removeMember. If a member is removed, all group members will receive a notification of NIMMessageType.notification type and the trigger event is kickMember.

Parameters:

Parameter	Description
teamId	group ID
members	The members to be removed.

** Sample code:**

// teamId indicates the group ID, and `account` indicates the removed member account
    final result = await NimCore.instance.teamService.removeMembers(
      'teamId',
      ['accids'],
    );

Leave a group

You can leave a group by calling quitTeam.

Except the group owner, all other members can leave a group. If a member leaves a group, all group members will receive a notification of NIMMessageType.notification type and the trigger event is leaveTeam.

** Sample code:**

  final result = await NimCore.instance.teamService.quitTeam(
      'teamId',
    );

Dismiss a group

Only the group owner have the permission to dismiss a group.

Group owners can dismiss groups by calling dismissTeam.

If a group is dismissed, all group members will receive a notification of MsgTypeEnum.notification type and the trigger event is dismissTeam.

** Sample code:**

  final result = await NimCore.instance.teamService.dismissTeam(
        'teamId'
    );

Edit the group profile

Members must have permissions for editing group profiles. If the edit permission of the group profile ([teamUpdateMode] is set to manager, only the group owner and administrators can edit the group profile. If the value is set to all, all group members can edit the group information.

For information about group attributes, see NIMTeamUpdateFieldRequest.

Interface	Type	Description
setAnnouncement	String?	Set a group announcement
setBeInviteMode	NIMTeamBeInviteModeEnum	Get the verification type for invitations.
setExtension	String?	set the extension field of a group (user-defined on the client)
setIcon	String?	Set the avatar of a group. If the avatar resource is uploaded to the CommsEase server, use the NOS service
setIntroduce	String?	Add the introduction
setInviteMode	NIMTeamInviteModeEnum	Set the invite mode.
setName	String?	Set the name of a group
setTeamExtensionUpdateMode	NIMTeamExtensionUpdateModeEnum	Set the edit permission of the extension fields of group information
setTeamUpdateMode	NIMTeamUpdateModeEnum	Set the edit permission of group information
setVerifyType	NIMVerifyTypeEnum	Set the verification type for joining a group.
setMaxMemberCount	int	Set the maximum number of group members
toMap	Map<String, dynamic>?	Group attributes.

You can edit multiple fields of a group profile by calling updateTeamFields.

If the group profile is updated, all group members will receive a notification of NIMMessageType.notification and the trigger event is updateTeam.

Parameters:

Parameter	Description
teamId	group ID
request	The new values of all fields to be updated. For more information, see [NIMTeamUpdateFieldRequest](https://doc.commsease.com/docs/interface/NIM_SDK/en/Latest/Flutter/nim_core/NIMTeamUpdateFieldRequest-class. html)

** Sample code:**

// Edit the name, introduction, and announcement
 NIMTeamUpdateFieldRequest request = NIMTeamUpdateFieldRequest();
 request.setName('New group name');
 request.setIntroduce('New group introduction');
 request.setAnnouncement('New announcement');
 final result = await NimCore.instance.teamService.updateTeamFields(
          teamId,
          request,
        );

Query group information

Query all groups the current user has joined.

Query all groups the current user has joined in the local database by asynchronous calling queryTeamList. The groups the current user leaves or groups from which the current user is removed are not returned. Sample code:

final result = await NimCore.instance.teamService.queryTeamList();
        handleCaseResult = ResultBean(
            code: result.code, message: methodName, data: result.data);

Query a specified group

Query a specified group by asynchronous calling queryTeam from the local database.

• If the data of the group information does not exist in the local database, retrieve the data from the server.
• If the current user does not belong to the group, the interface returns expired data. To update the group information, call searchTeam to retrieve the data from the server.

Sample code:

     final result = await NimCore.instance.teamService
        .queryTeam('teamId');

** Local storage of group information in the SDK:**

When you dismiss or leave a group, or are removed from the group, the local database will continue to retain the group information. Only the invalid flag is applied. At this time, you can still check the group member information using queryTeam. However, isMyTeam returns false. If the user manually clears all local data, the server will not synchronize the invalid group data during the next login synchronization, and the information about the group the user has left will not be obtained.

• After the group is dismissed, querying from the server using the searchTeam interface will return null .

Query a specified group from the server

• Query a specified group from the server by calling searchTeam. Sample code:

  final result = await NimCore.instance.teamService
        .searchTeam('teamId');

Group search

• Query group IDs by gruop name using searchTeamIdByName. Sample code:

 final result = await NimCore.instance.teamService.searchTeamIdByName(
          'name',
        );

• Query all groups using keywords by calling searchTeamsByKeyword.

Sample code:

final result = await NimCore.instance.teamService.searchTeamsByKeyword(
          'keyword',
        );

API reference

API	Description
createTeam	Create a group
addMembersEx	Invite users to join a group
acceptInvite	Accept an invitation to join a group
declineInvite	Reject an invitation to join a group
applyJoinTeam	Request to join a group
passApply	Approve a join request
rejectApply	Reject a join request
removeMembers	Remove members from a group.
quitTeam	Leave a group
transferTeam	Transfer the ownership of a group
dismissTeam	Dismiss a group
updateTeamFields	Update multiple fields of a group profile
queryTeamList	Query all groups the current user has joined.
queryTeam	Query the specified group information
searchTeam	Query multiple specified groups from the server
searchTeamIdByName	Query group IDs by gruop name
searchTeamsByKeyword	Query all groups by keyword.