Manage group channels

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

Group events

Group events are delivered through GroupChannelHandler and cover operations, group info changes, member info changes, membership requests, and favorites sync.

tip

In managed group services, SDK notifications from group operations are counted in message distribution statistics, regardless of whether your app implements event listeners.

Swift

swift

import NexconnChatSDK

final class GroupEventService: NSObject, GroupChannelHandler {
    func start() {
        NCEngine.addGroupChannelHandler(identifier: "GROUP_HANDLER", handler: self)
    }

    func onGroupOperation(_ event: GroupOperationEvent) {
        print("Group operation: \(event.groupId), \(event.operation.rawValue)")
    }

    func onGroupInfoChanged(_ event: GroupInfoChangedEvent) {
        print("Group info changed: \(event.groupInfo.groupId), fields: \(event.changedProperties)")
    }

    func onGroupMemberInfoChanged(_ event: GroupMemberInfoChangedEvent) {
        print("Group member updated: \(event.memberInfo.userId)")
    }

    func onGroupApplicationEvent(_ event: GroupApplicationEvent) {
        print("Group application event: \(event.info.groupId)")
    }

    func onGroupFavoritesChangedSync(_ event: GroupFavoritesChangedSyncEvent) {
        print("Group favorites changed: \(event.groupId), users: \(event.userIds)")
    }
}

Objective-C

Objective C

[NCEngine addGroupChannelHandlerWithIdentifier:@"GROUP_HANDLER" handler:self];

- (void)onGroupOperation:(NCGroupOperationEvent *)event {
    // event.groupId, event.operation, event.operatorInfo, event.memberInfos, event.operationTime
}

- (void)onGroupInfoChanged:(NCGroupInfoChangedEvent *)event {
    // event.operatorInfo, event.groupInfo, event.changedProperties, event.operationTime
}

- (void)onGroupMemberInfoChanged:(NCGroupMemberInfoChangedEvent *)event {
    // event.groupId, event.operatorInfo, event.memberInfo, event.operationTime
}

- (void)onGroupApplicationEvent:(NCGroupApplicationEvent *)event {
    // event.info
}

- (void)onGroupFavoritesChangedSync:(NCGroupFavoritesChangedSyncEvent *)event {
    // event.groupId, event.operationType, event.userIds, event.operationTime
}

Group management

Create a group

Call GroupChannel.createGroup(params:completion:) to create a new group:

Swift

swift

import NexconnChatSDK

let params = CreateGroupParams(groupId: "groupId", groupName: "groupName")
params.inviteeUserIds = ["user1", "user2"]
params.portraitUri = "https://example.com/avatar.jpg"

GroupChannel.createGroup(params: params) { processCode, errorKeys, error in
    if let error {
        print("Failed to create group: \(error.localizedDescription), fields: \(errorKeys ?? [])")
        return
    }

    print("Group created. processCode = \(processCode)")
}

Objective-C

Objective C

NCCreateGroupParams *params = [[NCCreateGroupParams alloc] initWithGroupId:@"groupId" groupName:@"groupName"];
params.inviteeUserIds = @[@"user1", @"user2"];
params.portraitUri = @"https://example.com/avatar.jpg";

[NCGroupChannel createGroupWithParams:params
                           completion:^(NSInteger processCode, NSArray<NSString *> * _Nullable errorKeys, NCError * _Nullable error) {
    if (!error) {
        // Group created successfully
        // processCode 25427 means invitee verification is required
    }
}];

CreateGroupParams properties:

Property	Type	Required	Description
groupId	NSString	Yes	Group ID. Provided in the initializer.
groupName	NSString	Yes	Group name. Provided in the initializer.
inviteeUserIds	NSArray	No	Initial member IDs. Max 30 per request.
portraitUri	NSString	No	Avatar URL.
introduction	NSString	No	Group description.
notice	NSString	No	Group announcement.
extProfile	NSDictionary	No	Custom properties configured in the Console first.
joinPermission	NCGroupJoinPermission	No	Join permission. Default is owner verification.
removeMemberPermission	NCGroupOperationPermission	No	Kick permission. Default is owner only.
invitePermission	NCGroupOperationPermission	No	Invite permission. Default is owner only.
inviteHandlePermission	NCGroupInviteHandlePermission	No	Invitee approval. Default is no approval required.
groupInfoEditPermission	NCGroupOperationPermission	No	Info edit permission. Default is owner only.
memberInfoEditPermission	NCGroupMemberInfoEditPermission	No	Member info edit permission.

tip

• The group creation result is not affected by processCode. A callback without error means the group was created.
• The channel owner receives onGroupOperation(_:) with type create.

Update group info

Call updateInfo(params:completion:) on a GroupChannel instance to modify group properties. Only non-nil fields are updated.

Swift

swift

import NexconnChatSDK

guard let channel = GroupChannel(channelId: "groupId") else {
    return
}

let params = UpdateGroupInfoParams()
params.groupName = "New Group Name"
params.notice = "New announcement"
params.setJoinPermission(.free)

channel.updateInfo(params: params) { errorKeys, error in
    if error == nil {
        print("Group info updated.")
    } else {
        print("Failed fields: \(errorKeys ?? [])")
    }
}

Objective-C

Objective C

NCGroupChannel *channel = [[NCGroupChannel alloc] initWithChannelId:@"groupId"];
NCUpdateGroupInfoParams *params = [[NCUpdateGroupInfoParams alloc] init];
params.groupName = @"New Group Name";
params.notice = @"New announcement";
params.joinPermissionValue = @(NCGroupJoinPermissionFree);

[channel updateInfoWithParams:params
                   completion:^(NSArray<NSString *> * _Nullable errorKeys, NCError * _Nullable error) {
    if (!error) {
        // Updated
    }
}];

Kick members

Call kickMembers(params:completion:) to remove members. All members receive onGroupOperation(_:) with type kick.

Swift

swift

import NexconnChatSDK

guard let channel = GroupChannel(channelId: "groupId") else {
    return
}

let params = KickGroupMembersParams()
params.userIds = ["user1", "user2"]

let config = LeaveGroupConfig()
config.deleteMuteStatus = true
params.config = config

channel.kickMembers(params: params) { error in
    if error == nil {
        print("Members kicked.")
    }
}

Objective-C

Objective C

NCGroupChannel *channel = [[NCGroupChannel alloc] initWithChannelId:@"groupId"];
NCKickGroupMembersParams *params = [[NCKickGroupMembersParams alloc] init];
params.userIds = @[@"user1", @"user2"];

NCLeaveGroupConfig *config = [[NCLeaveGroupConfig alloc] init];
config.deleteMuteStatus = YES;
params.config = config;

[channel kickMembersWithParams:params completion:^(NCError * _Nullable error) {
    if (!error) {
        // Kicked
    }
}];

Leave a group

Call leave(config:completion:) to leave a group. All members receive onGroupOperation(_:) with type quit.

Swift

swift

import NexconnChatSDK

guard let channel = GroupChannel(channelId: "groupId") else {
    return
}

channel.leave(config: nil) { error in
    if error == nil {
        print("Left the group.")
    }
}

Objective-C

Objective C

NCGroupChannel *channel = [[NCGroupChannel alloc] initWithChannelId:@"groupId"];
[channel leaveWithConfig:nil completion:^(NCError * _Nullable error) {
    if (!error) {
        // Left the group
    }
}];

Dismiss a group

Call dismiss(completion:) to dismiss a group. Messages remain locally. All members receive onGroupOperation(_:) with type dismiss.

tip

Only the channel owner can dismiss a group.

Swift

swift

import NexconnChatSDK

guard let channel = GroupChannel(channelId: "groupId") else {
    return
}

channel.dismiss { error in
    if error == nil {
        print("Group dismissed.")
    }
}

Objective-C

Objective C

NCGroupChannel *channel = [[NCGroupChannel alloc] initWithChannelId:@"groupId"];
[channel dismissWithCompletion:^(NCError * _Nullable error) {
    if (!error) {
        // Dismissed
    }
}];

Transfer ownership

Call transferOwner(params:completion:) to transfer ownership. All members receive onGroupOperation(_:) with type transfer.

tip

Only the channel owner can transfer ownership.

Swift

swift

import NexconnChatSDK

guard let channel = GroupChannel(channelId: "groupId") else {
    return
}

let params = TransferGroupOwnerParams()
params.newOwnerId = "newOwnerId"
params.leaveAfterTransfer = true

channel.transferOwner(params: params) { error in
    if error == nil {
        print("Ownership transferred.")
    }
}

Objective-C

Objective C

NCGroupChannel *channel = [[NCGroupChannel alloc] initWithChannelId:@"groupId"];
NCTransferGroupOwnerParams *params = [[NCTransferGroupOwnerParams alloc] init];
params.newOwnerId = @"newOwnerId";
params.leaveAfterTransfer = YES;

[channel transferOwnerWithParams:params completion:^(NCError * _Nullable error) {
    if (!error) {
        // Transferred
    }
}];

Group nickname

Group nicknames are user-specific. When a new message arrives and the user is offline, the push notification title shows the group nickname if set, otherwise the group name.

Set a group nickname

Use setMemberInfo(params:completion:) on a group channel instance. Pass nil or "" as nickname to remove the nickname.

Swift

swift

import NexconnChatSDK

guard let channel = GroupChannel(channelId: "groupId") else {
    return
}

let params = SetGroupMemberInfoParams()
params.userId = NCEngine.getCurrentUserId() ?? ""
params.nickname = "My Team"

channel.setMemberInfo(params: params) { errorKeys, error in
    if error == nil {
        print("Nickname set.")
    } else {
        print("Failed fields: \(errorKeys ?? [])")
    }
}

Objective-C

Objective C

NCGroupChannel *channel = [[NCGroupChannel alloc] initWithChannelId:@"groupId"];
NCSetGroupMemberInfoParams *params = [[NCSetGroupMemberInfoParams alloc] init];
params.userId = [NCEngine getCurrentUserId];
params.nickname = @"My Team";

[channel setMemberInfoWithParams:params
                      completion:^(NSArray<NSString *> * _Nullable errorKeys, NCError * _Nullable error) {
    if (!error) {
        // Nickname set
    }
}];

Get group info (including nickname)

Swift

swift

import NexconnChatSDK

GroupChannel.getGroupsInfo(groupIds: ["groupId"]) { groupInfos, error in
    guard let remark = groupInfos?.first?.remark, error == nil else {
        return
    }

    print("Group nickname: \(remark)")
}

Objective-C

Objective C

[NCGroupChannel getGroupsInfoWithGroupIds:@[@"groupId"] completion:^(NSArray<NCGroupInfo *> * _Nullable groupInfos, NCError * _Nullable error) {
    NSString *remark = groupInfos.firstObject.remark;
}];