Manage group channels

tip

Groups created outside the managed hosting APIs require importing managed hosting data (setting the channel owner and default permissions) before using managed group features.

Prerequisites

The managed hosting service is enabled by default.

Group event listeners

Register a GroupChannelHandler to receive group application and other events:

Dart

NCEngine.addGroupChannelHandler('group-handler', GroupChannelHandler(
  onGroupApplicationEvent: (event) {
    print('Group application event: ${event.info}');
  },
  onGroupInfoChanged: (event) {
    print('Group info changed: ${event.fullGroupInfo?.groupName}');
  },
  onGroupFavoritesChangedSync: (event) {
    print('Group favorites changed: ${event.groupId}');
  },
));

Remove the handler when it is no longer needed:

Dart

NCEngine.removeGroupChannelHandler('group-handler');

Create a group

Call GroupChannel.createGroup() to create a new group channel.

CreateGroupParams properties

Property	Type	Required	Description
groupId	String	Yes	Group ID (max 64 characters, alphanumeric)
groupName	String?	No	Group name (max 64 characters)
avatarUrl	String?	No	Avatar URL (max 128 characters)
introduction	String?	No	Description (max 512 characters)
notice	String?	No	Announcement (max 1024 characters)
extProfile	Map?	No	Custom properties (max 10, configure in console first)
joinPermission	GroupJoinPermission	No	Join permission (default: owner approval required)
removeMemberPermission	GroupOperationPermission	No	Remove permission (default: owner only)
invitePermission	GroupOperationPermission	No	Invite permission (default: owner only)
inviteHandlePermission	GroupInviteHandlePermission	No	Invitee approval (default: not required)
groupInfoEditPermission	GroupOperationPermission	No	Edit permission (default: owner only)
memberInfoEditPermission	GroupMemberInfoEditPermission	No	Member profile edit permission
inviteeUserIds	List<String>	Yes	Initial users to invite into the group

Dart

await GroupChannel.createGroup(
  CreateGroupParams(
    groupId: 'groupId',
    groupName: 'groupName',
    inviteeUserIds: ['userId1', 'userId2', 'userId3'],
  ),
  (errorKeys, processCode, error) {
    if (error == null) {
      print('Group created, processCode: $processCode');
    } else {
      print('Create failed: ${error.code}, errorKeys: $errorKeys');
    }
  },
);

GroupChannel.createGroup() uses OperationWithProcessCodeHandler<List<String>>, not ErrorHandler. For this callback type:

• Success: processCode is available, while errorKeys and error are null
• Failure: error is not null, and errorKeys may contain the native-layer field keys that failed validation or update

The remaining instance methods on this page use ErrorHandler instead. For those callbacks, success means error?.isSuccess == true (error.code == 0).

If you need the created group's full details after a successful create call, follow up with GroupChannel.getGroupsInfo([groupId], ...).

Update group info

Call group.updateInfo() on the GroupChannel instance. The target group ID comes from the current GroupChannel.channelId, so UpdateGroupInfoParams only contains editable fields.

Dart

final group = GroupChannel('groupId');
await group.updateInfo(
  UpdateGroupInfoParams(groupName: 'New Name'),
  (errorInfo, error) {
    if (error?.isSuccess == true) {
      print('Group info updated');
    } else {
      print('Update failed: $errorInfo');
    }
  },
);

Remove members

Call group.kickMembers() to remove members (up to 100 per call).

Dart

await group.kickMembers(
  KickGroupMembersParams(
    userIds: ['userId1', 'userId2'],
    config: LeaveGroupConfig(),
  ),
  (error) {
    if (error?.isSuccess == true) {
      print('Members removed');
    }
  },
);

Leave a group

Dart

await group.leave(
  LeaveGroupConfig(),
  (error) {
    if (error?.isSuccess == true) {
      print('Left group');
    }
  },
);

Dismiss a group

Call group.dismiss(). Only the channel owner can dismiss.

Dart

await group.dismiss((error) {
  if (error?.isSuccess == true) {
    print('Group dismissed');
  }
});

Transfer ownership

Dart

await group.transferOwner(
  TransferGroupOwnerParams(
    newOwnerId: 'newOwnerUserId',
    config: LeaveGroupConfig(),
  ),
  (error) {
    if (error?.isSuccess == true) {
      print('Ownership transferred');
    }
  },
);

Group remark

Dart

await group.setRemark(
  'My Group',
  (error) {
    if (error?.isSuccess == true) {
      print('Remark set');
    }
  },
);