Managing groups

This document guides developers on how to use RC's instant messaging Web IMLib SDK to implement group creation, group profile settings, member removal, group exit, group dissolution, and group ownership transfer.

tip

• This feature is supported starting from version 5.12.0.
• For groups created through the legacy group API /group/create.json, you must call the Group Information Hosting import API to set the group owner and default permissions before using related hosting features.

Enabling the Service

Before using this feature, you must enable the profile hosting service by submitting a ticket.

Group Operations

Group Operation Event Notification

Group operations include: create group, update group profile, remove member, exit group, dissolve group, and transfer ownership. You can distinguish operation types via the operation field in IGroupOperationInfo.

tip

• Register event listeners globally and only once to avoid duplicate notifications.
• The event callback data type is IGroupOperationInfo.

Sample Code

RongIMLib.addEventListener(Events.GROUP_OPERATION, (data) => {
  // data is of type IGroupOperationInfo, use operation to determine the action type
  console.log('Group operation changed', data);
});

Group Profile Update Notification

When updateGroupInfo is called successfully, all group members will receive the Events.GROUP_INFO_CHANGED event.

tip

• Register event listeners globally and only once to avoid duplicate notifications.
• The event callback data type is IGroupInfoChanged.
• Notification data only includes modified fields - unchanged fields won't be included

Sample Code

RongIMLib.addEventListener(Events.GROUP_INFO_CHANGED, (data) => {
  console.log('Group profile update notification', data);
});

Create Group

Call createGroup to create a new group.

Interface

RongIMLib.createGroup(groupInfo, inviteeUserIds)

Parameters

Parameter	Type	Required	Description
groupInfo	IGroupInfoOption	Yes	Group information.
inviteeUserIds	string[]	No	Optional member invitation list (max 30 users). Empty means no invitations.

• groupInfo parameters:

Property	Type	Required	Description
groupId	string	Yes	Group ID: Max 64 characters. Supports alphanumeric combinations.
groupName	string	Yes	Group name: Max 64 characters. Cannot be blank spaces.
portraitUri	string	No	Group avatar URL: Max 128 characters.
introduction	string	No	Group introduction: Max 512 characters.
notice	string	No	Group announcement: Max 1024 characters.
extProfile	{[key: string]: string}	No	Extended Information: Add up to 10 custom attributes (Key/Value pairs) for business needs. Must be configured via developer backend or API first.
joinPermission	GroupJoinPermission	No	Join permission: No verification (default), owner verification, owner+admin verification, or no joining allowed. Default used if unset.
removeMemberPermission	GroupOperationPermission	No	Member removal permission: Owner (default), owner+admins, or all members. Default used if unset.
invitePermission	GroupOperationPermission	No	Invitation permission: Owner (default), owner+admins, or all members. Default used if unset.
inviteHandlePermission	GroupInviteHandlePermission	No	Invitation handling: No consent needed (default) or invitee consent required. Default used if unset.
groupInfoEditPermission	GroupOperationPermission	No	Profile/permission editing: Owner (default), owner+admins, or all members. Only owners can modify this.
memberInfoEditPermission	GroupMemberInfoEditPermission	No	Member profile editing: Self-only, owner+self, or owner+admins+self (default). Default used if unset.

Sample Code

const groupInfo = {
  // Required, max 64 characters. Alphanumeric combinations
  groupId: 'group001',
  // Required, max 64 characters
  groupName: 'groupName',
  // Custom attributes must be configured first via backend/API
  extProfile: {},
};

const memberIdsArr = ['userId001', 'userId002'];
const res = await RongIMLib.createGroup(groupInfo, memberIdsArr);
console.info('Group creation result', res);

tip

1. On successful creation, the owner receives Events.GROUP_OPERATION with operation value 0 (enum GroupOperation.CREATE).

2. When inviteeUserIds is set and inviteHandlePermission is GroupInviteHandlePermission.FREE, invitees join automatically. All members receive Events.GROUP_OPERATION with operation value 1 (enum GroupOperation.JOIN).

3. When inviteeUserIds is set and inviteHandlePermission is GroupInviteHandlePermission.INVITEE_VERIFY:

   • The API returns processCode 25427, indicating invitee consent is required.
   • Invitees receive Events.GROUP_APPLICATION_EVENT and must call acceptGroupInvite to join.

INVITEE_VERIFY):

• The API returns processCode 25427, indicating invitee consent is required to join the group.
• Invitees receive Events.GROUP_APPLICATION_EVENT and must call acceptGroupInvite to join.

Update group info

Call updateGroupInfo to modify group name, announcement, permissions, etc.

tip

• Only groupId is required; other fields are optional. The API only updates provided fields, leaving unspecified fields unchanged.
• After successful update, members receive Events.GROUP_INFO_CHANGED containing only changed fields.

Interface

RongIMLib.updateGroupInfo(groupInfo)

Parameters

Parameter	Type	Required	Description
groupInfo	IGroupInfoOption	Yes	Group information.

Example

const groupInfo = {
  // Required, max 64 characters. Supports alphanumeric combinations
  groupId: 'group001',
  introduction: 'group introduction',
};

const res = await RongIMLib.updateGroupInfo(groupInfo);
console.info('Group info update result', res);

Remove group members

Call kickGroupMembers to remove members (max 100 per operation).

tip

• Members receive Events.GROUP_OPERATION with operation=2 (GroupOperation.KICK) upon success.
• Group owners cannot be removed.
• Operation requires removeMemberPermission.

Interface

RongIMLib.kickGroupMembers(groupId, userIds, config)

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID.
userIds	string[]	Yes	Member IDs to remove.
config	IQuitGroupConfig	No	Controls whether to remove followed users, allowlist users, and mute status. Default removes all if unspecified.

Example

const groupId = 'group001';
const memberIds = ['user01', 'user02'];
const config = {
    removeMuteStatus: true, 
    removeWhiteList: true,
    removeFollow: true,
  }
const res = await RongIMLib.kickGroupMembers(groupId, memberIds, config)
console.info('Member removal result', res);

Leave group

Call quitGroup to voluntarily leave a group.

tip

Members receive Events.GROUP_OPERATION with operation=3 (GroupOperation.QUIT) upon success.

Interface

RongIMLib.quitGroup(groupId, config)

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID.
config	IQuitGroupConfig	No	Controls whether to remove followed users, allowlist users, and mute status. Default removes all if unspecified.

Example

const groupId = 'group001';
const res = await RongIMLib.quitGroup(groupId)
console.info('Group leave result', res);

tip

1. Group owners receive error code 25417 when calling quitGroup.
2. Owners must first transfer ownership via transferGroupOwner before leaving.

Dismiss group

Call dismissGroup to disband a group (retains conversation history).

tip

• Only group owners can disband groups.
• Members receive Events.GROUP_OPERATION with operation=4 (GroupOperation.DISMISS) upon success.

Interface

RongIMLib.dismissGroup(groupId)

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID.

Example

const groupId = 'group001';
const res = await RongIMLib.dismissGroup(groupId)
console.info('Group dismissal result', res);

Transfer group ownership

Call transferGroupOwner to transfer group ownership.

tip

• Only owners can transfer.
• Members receive Events.GROUP_OPERATION with operation=7 (GroupOperation.TRANSFER_GROUP_OWNER) upon success.
• If quitting the group during transfer, members also receive operation=3 (GroupOperation.QUIT).

Interface

RongIMLib.transferGroupOwner(groupId, newOwnerId, quitGroup, config);

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID.
newOwnerId	string	Yes	New owner's user ID.
quitGroup	boolean	No	Whether to quit group after transfer (default false).
config	IQuitGroupConfig	No	Only applies when quitGroup=true. Controls whether to remove followed users, allowlist users, and mute status. Default removes all if unspecified.

Example

const groupId = 'group001';
const newOwnerId = 'newOwnerId';
const quitGroup = true; 
const config = {
    removeMuteStatus: true, 
    removeWhiteList: true,
    removeFollow: true,
}
const res = await RongIMLib.transferGroupOwner(groupId, newOwnerId, quitGroup, config);
console.info('Ownership transfer result', res);

Group Alias

The Group Alias only applies to the current user. When new messages are generated in the group and the user is offline, the push notification title will preferentially display the set group alias. If not set, the group name will be displayed by default.

Multi-device Synchronization Notification for Group Alias Updates

When a group alias is set or removed successfully, other logged-in devices will receive the Events.GROUP_REMARK_CHANGED_SYNC event notification to achieve multi-device synchronization.

tip

• The event listener should be registered globally and only once to avoid duplicate event notifications.
• The event callback data type is IGroupRemarkChangedSync.

Example code

RongIMLib.addEventListener(Events.GROUP_REMARK_CHANGED_SYNC, (data) => {
  console.log('Multi-device synchronization notification for group alias updates', data);
});

Set Group Alias

Call the setGroupRemark method to set a group alias.

Interface

RongIMLib.setGroupRemark(groupId, remark)

Parameter description

Parameter	Type	Required	Description
groupId	string	Yes	Group ID.
remark	string	Yes	Group alias. Set to '' to remove. Cannot be pure spaces. String length should not exceed 64 characters. If the group alias already exists, it will be replaced, with the last setting taking precedence.

Example code

const groupId = 'group001';
// Set to '' to remove. String length should not exceed 64 characters. If the group alias already exists, it will be replaced, with the last setting taking precedence.
const remark = 'remark';
const res = await RongIMLib.setGroupRemark(groupId, remark);
// You must input an existing group ID; otherwise, the group information cannot be queried, and the console may throw an exception.
console.info('Group alias setting result', res);

Query Group Alias

You can query group information, including the group alias, using the getGroupsInfo method.

Interface

RongIMLib.getGroupsInfo(groupIds)

Parameter description

Parameter	Type	Required	Description
groupIds	string[]	Yes	Array of group IDs. A single query supports up to 20 groups.

warning

If you input a non-existent group ID, the information cannot be queried, and the console may throw an exception.

Example code

// Required. Array of group IDs. A single query supports up to 20 groups.
const groupIds = ['group001']
const res = await RongIMLib.getGroupsInfo(groupIds);
// You must input an existing group ID; otherwise, the group information cannot be queried, and the console may throw an exception.
console.info('Group alias', res[0].remark);