Skip to main content

Managing group channels

This guide covers how to create groups, update group profiles, kick members, leave groups, dismiss groups, and transfer ownership using the Nexconn SDK.

Group event listener​

Group events are defined in GroupChannelHandler, including group operations, group/member profile changes, membership request notifications, and cross-device favorites sync events.

kotlin
NCEngine.addGroupChannelHandler("GROUP_HANDLER", object : GroupChannelHandler {
    override fun onGroupOperation(event: GroupOperationEvent) {
        // Group operation callback: create, join, kick, leave, dismiss, add/remove admin, transfer, etc.
    }
    
    override fun onGroupInfoChanged(event: GroupInfoChangedEvent) {
        // Group profile changed
    }
    
    override fun onGroupMemberInfoChanged(event: GroupMemberInfoChangedEvent) {
        // Member profile changed
    }
    
    override fun onGroupApplicationEvent(event: GroupApplicationInfo) {
        // Membership request event: join request or invite
    }

    override fun onGroupFavoritesChangedSync(event: GroupFavoritesChangedSyncEvent) {
        // Cross-device favorites sync event
    }
})

Remove listener​

kotlin
NCEngine.removeGroupChannelHandler("GROUP_HANDLER")
tip

Group operation SDK notification callbacks are also a form of status notification. Regardless of whether the app implements event listeners, the server syncs status to the SDK to ensure local data is up to date. These notifications count toward message distribution and downstream statistics.

Group management​

Group management includes: creating groups, updating profiles, kicking members, leaving groups, dismissing groups, and transferring ownership.

Create a group​

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

kotlin
val params = CreateGroupParams(
    groupId = "group_123",
    groupName = "Tech Discussion",
    inviteeUserIds = listOf("userId1", "userId2", "userId3")
).apply {
    portraitUri = "https://example.com/group-avatar.png"
    introduction = "A group for technical discussions"
    notice = "Welcome to the group"
    joinPermission = GroupJoinPermission.OWNER_VERIFY
    removeMemberPermission = GroupOperationPermission.OWNER_AND_ADMIN
    invitePermission = GroupOperationPermission.ALL
}

GroupChannel.createGroup(params) { resultCode, error ->
    if (error == null) {
        // Created successfully
    } else {
        // Creation failed: ${error.message}
    }
}

Group profile parameters​

PropertyTypeRequiredDescription
groupIdStringYesGroup ID. Max 64 characters. Alphanumeric only.
groupNameStringYesGroup name. Max 64 characters.
portraitUriStringNoGroup avatar URL. Max 128 characters.
introductionStringNoGroup description. Max 512 characters.
noticeStringNoGroup notice/announcement. Max 1024 characters.
extProfileMap<String, String>NoCustom extension fields. Up to 10. Must be configured in the Console first.
joinPermissionGroupJoinPermissionNoJoin permission: no verification, owner approval (default), owner+admin approval, or no one allowed.
removeMemberPermissionGroupOperationPermissionNoKick permission: owner only (default), owner+admin, or all members.
invitePermissionGroupOperationPermissionNoInvite permission: owner only (default), owner+admin, or all members.
inviteHandlePermissionGroupInviteHandlePermissionNoWhether invitees must accept: no approval needed (default), or invitee must accept.
groupInfoEditPermissionGroupOperationPermissionNoProfile edit permission: owner only (default), owner+admin, or all. Only the owner can change this.
memberInfoEditPermissionGroupMemberInfoEditPermissionNoMember profile edit permission: self only, owner+self, or owner+admin+self (default).

inviteeUserIds Parameter​

You can invite users when creating the group. Maximum 30 users per invitation.

The result depends on the inviteHandlePermission setting:

  • If invitee approval is required, invitees receive an onGroupApplicationEvent and must accept before joining.
  • If no approval is required, invitees are added directly.
tip
  • A successful callback means the group was created successfully.
  • On creation, the owner receives an onGroupOperation callback with GroupOperation type Create.

Update group profile​

Call groupChannel.updateGroupInfo() to update the group name, notice, permissions, or other profile fields. Only groupId is required; the API updates only the fields you provide.

tip
  • After a successful update, all channel members receive an onGroupInfoChanged callback.
  • Edit permission is controlled by groupInfoEditPermission. Only the channel owner can change this permission.
kotlin
val groupChannel = GroupChannel("groupId")

val params = UpdateGroupInfoParams().apply {
    groupName = "New Group Name"
    notice = "New group notice"
}

groupChannel.updateInfo(params) { errorKeys, error ->
    if (error == null) {
        // Updated successfully
    } else {
        // Update failed. errorKeys contains the failed field names.
    }
}

Kick members​

Call groupChannel.kickMembers() to remove users from the group. Supports batch removal of up to 100 users at once.

Use LeaveGroupConfig to control whether to also remove Favorites (followed users), allowed senders list entries, and mute status. By default, all are removed.

The removeMemberPermission setting determines whether the caller has kick permission.

tip

On success, all channel members receive an onGroupOperation callback with GroupOperation type Kick.

kotlin
val groupChannel = GroupChannel("groupId")

val config = LeaveGroupConfig().apply {
    isRemoveFollow = false
    isRemoveWhiteList = false
    isRemoveMuteStatus = false
}

val params = KickGroupMembersParams(listOf("userId1", "userId2", "userId3")).apply {
    this.config = config
}

groupChannel.kickMembers(params) { error ->
    if (error == null) {
        // Kick succeeded
    } else {
        // Kick failed: ${error.message}
    }
}

Leave a group​

Call groupChannel.leave() to leave a group voluntarily.

Use LeaveGroupConfig to control whether to also remove Favorites, allowed senders list entries, and mute status. By default, all are removed on leave.

tip

On success, all channel members receive an onGroupOperation callback with GroupOperation type Quit.

kotlin
val groupChannel = GroupChannel("groupId")

val config = LeaveGroupConfig().apply {
    isRemoveFollow = false
    isRemoveWhiteList = false
    isRemoveMuteStatus = false
}

groupChannel.leave(config) { error ->
    if (error == null) {
        // Left successfully
    } else {
        // Leave failed: ${error.message}
    }
}

Dismiss a group​

Call groupChannel.dismiss() to dismiss a group. Messages in the channel are preserved locally after dismissal.

tip
  • Only the channel owner can dismiss a group.
  • On success, all members receive an onGroupOperation callback with GroupOperation type Dismiss.
kotlin
val groupChannel = GroupChannel("groupId")

groupChannel.dismiss { error ->
    if (error == null) {
        // Dismissed successfully
    } else {
        // Dismiss failed: ${error.message}
    }
}

Transfer ownership​

Call groupChannel.transferOwner() to transfer the channel owner role to another user.

You can choose whether to leave the group after the transfer (quitGroup). If set to true, use LeaveGroupConfig to control cleanup behavior.

On success, all members receive an onGroupOperation callback with type TransferGroupOwner. If you also chose to leave, an additional Quit event is sent.

tip

Only the channel owner can transfer ownership.

kotlin
val groupChannel = GroupChannel("groupId")

val config = LeaveGroupConfig().apply {
    isRemoveFollow = false
    isRemoveWhiteList = false
    isRemoveMuteStatus = false
}

val params = TransferGroupOwnerParams("userId1").apply {
    leaveAfterTransfer = true
    this.config = config
}

groupChannel.transferOwner(params) { error ->
    if (error == null) {
        // Transfer succeeded
    } else {
        // Transfer failed: ${error.message}
    }
}
Last updated on