Managing groups

This document guides developers on how to use the RC Instant Messaging Web IMLib SDK to implement group-related functions such as creating groups, setting group profiles, removing members from groups, leaving groups, disbanding groups, and transferring group ownership.

tip

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

Service Activation

The User Profile Hosting service is enabled by default and can be used directly.

Group Operations

Group Operation Event Notification

Group operations include: creating groups, setting group profiles, removing members from groups, leaving groups, disbanding groups, and transferring group ownership. Operation types can be distinguished via the operation field in IGroupOperationInfo.

tip

• Event listeners should be registered 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 operation type
  console.log('Group operation change', data);
});

Group Profile Change Notification

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

tip

• Event listeners should be registered globally and only once to avoid duplicate notifications.
• The event callback data type is IGroupInfoChanged.
• Notification data only includes modified fields; unchanged fields are not included

Sample Code

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

Create Group

Call the createGroup method to create a new group.

Interface

RongIMLib.createGroup(groupInfo, inviteeUserIds)

Parameter Description

Parameter	Type	Required	Description
groupInfo	IGroupInfoOption	Yes	Group information.
inviteeUserIds	string[]	No	Optional list of invited members (max 30). Leave empty to invite no members.

• groupInfo Parameter Description:

Property	Type	Required	Description
groupId	string	Yes	Group ID: Max length 64 characters. Supports alphanumeric combinations.
groupName	string	Yes	Group name: Max length 64 characters. Cannot be empty spaces.
portraitUri	string	No	Group avatar URL: Max length 128 characters.
introduction	string	No	Group introduction: Max length 512 characters.
notice	string	No	Group announcement: Max length 1024 characters.
extProfile	{[key: string]: string}	No	Extended Information: Developers can add custom attributes (Key-Value pairs) based on business needs, with a maximum of 10 extensions. Custom attributes must be configured via the developer console or API before use; otherwise, the operation will fail.
joinPermission	GroupJoinPermission	No	Group join permission: No verification (default), owner verification, owner+admin verification, or no one allowed. Defaults to owner verification if not set.
removeMemberPermission	GroupOperationPermission	No	Permission to remove members: Owner (default), owner+admins, or all members. Defaults to owner if not set.
invitePermission	GroupOperationPermission	No	Permission to invite others: Owner (default), owner+admins, or all members. Defaults to owner if not set.
inviteHandlePermission	GroupInviteHandlePermission	No	Invitation handling: No invitee consent required (default) or invitee consent required. Defaults to no consent if not set.
groupInfoEditPermission	GroupOperationPermission	No	Permission to edit group info and permissions: Owner (default), owner+admins, or all members. Defaults to owner if not set. Only the owner can modify this property.
memberInfoEditPermission	GroupMemberInfoEditPermission	No	Permission to edit member info: Only self, owner+self, or owner+admins+self (default). Defaults to owner+admins+self if not set.

Sample Code

const groupInfo = {
  // Required, max 64 characters. Supports alphanumeric combinations.
  groupId: 'group001',
  // Required, max 64 characters.
  groupName: 'groupName',
  // Custom attributes must be configured via the developer console or API before use.
  extProfile: {},
};

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

tip

1. Upon successful group creation, the owner receives the Events.GROUP_OPERATION event, where the operation field is 0, corresponding to the enum GroupOperation.CREATE.

2. When inviteeUserIds is set and inviteHandlePermission is GroupInviteHandlePermission.FREE, invitees automatically join the group. All members receive the Events.GROUP_OPERATION event, where the operation field is 1, corresponding to the enum GroupOperation.JOIN.

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

   • The API returns processCode 25427, indicating that invitee consent is required.
   • Invitees receive the 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 the provided fields.
• Upon successful update, members receive the Events.GROUP_INFO_CHANGED event, which only includes changed fields.

Interface

RongIMLib.updateGroupInfo(groupInfo)

Parameter Description

Parameter	Type	Required	Description
groupInfo	IGroupInfoOption	Yes	Group information.

Sample Code

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 Members from Group

Call the kickGroupMembers method to remove members from a group, with a maximum of 100 members per operation.

tip

• Upon success, group members will receive the Events.GROUP_OPERATION event with operation=2 (GroupOperation.KICK).
• Group owners cannot be removed.
• This operation is subject to removeMemberPermission restrictions and can only be performed by authorized users.

Method

RongIMLib.kickGroupMembers(groupId, userIds, config)

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID.
userIds	string[]	Yes	List of member IDs to be removed.
config	IQuitGroupConfig	No	Configuration options to control whether to remove followed users, allowlist users, and muted members. If not set, all will be removed by default.

Example Code

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

Leave Group

Call the quitGroup method to voluntarily leave a group.

tip

Upon success, group members will receive the Events.GROUP_OPERATION event with operation=3 (GroupOperation.QUIT).

Method

RongIMLib.quitGroup(groupId, config)

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID.
config	IQuitGroupConfig	No	Configuration options to control whether to remove followed users, allowlist users, and muted members. If not set, all will be removed by default upon leaving.

Example Code

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

tip

1. Group owners calling quitGroup will receive status code 25417: Group owners cannot be removed/leave the group.
2. Group owners must first transfer ownership via transferGroupOwner before leaving the group.

Dismiss Group

Call the dismissGroup method to disband a group. Group conversation messages will be retained, but history messages will not be deleted.

tip

• Only group owners can disband groups.
• Upon success, members will receive the Events.GROUP_OPERATION event with operation=4 (GroupOperation.DISMISS).

Method

RongIMLib.dismissGroup(groupId)

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID.

Example Code

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

Transfer Group Ownership

Call the transferGroupOwner method to transfer group ownership to another user.

tip

• Only group owners can transfer ownership.
• Upon success, members will receive the Events.GROUP_OPERATION event with operation=7 (GroupOperation.TRANSFER_GROUP_OWNER).
• If the owner chooses to leave the group during transfer, an additional operation=3 (GroupOperation.QUIT) event will be triggered.

Method

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

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID.
newOwnerId	string	Yes	User ID of the new owner.
quitGroup	boolean	No	Whether to leave the group after transfer (default: false).
config	IQuitGroupConfig	No	Only effective when quitGroup is true. Controls whether to remove followed users, allowlist users, and muted members. If not set, all will be removed by default.

Example Code

// Required: Group ID
const groupId = 'group001';
// Required: New owner's user ID
const newOwnerId = 'newOwnerId';
// Whether to leave the group after transfer (default: false).
const quitGroup = true; 
// This config only applies when quitGroup is true
const config = {
    // Default: true (remove)
    removeMuteStatus: true, 
    // Default: true (remove)
    removeWhiteList: true,
    // Default: true (remove)
    removeFollow: true,
}
const res = await RongIMLib.transferGroupOwner(groupId, newOwnerId, quitGroup, config);
console.info('Group ownership transfer result', res);

Group Alias

Group aliases are user-specific. When new messages arrive while the user is offline, push notifications will display the alias (if set) instead of the group name.

Multi-Device Sync Notification for Group Alias Updates

When a group alias is set or removed, other logged-in devices will receive the Events.GROUP_REMARK_CHANGED_SYNC event for synchronization.

tip

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

Example Code

RongIMLib.addEventListener(Events.GROUP_REMARK_CHANGED_SYNC, (data) => {
  console.log('Group alias update sync notification', data);
});

Set Group Alias

Call the setGroupRemark method to set a group alias.

Method

RongIMLib.setGroupRemark(groupId, remark)

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID.
remark	string	Yes	Group alias. Set to '' to remove. Cannot be empty spaces. Max 64 characters. Existing aliases will be overwritten (last setting takes precedence).

Example Code

const groupId = 'group001';
// Set to '' to remove. Max 64 characters. Existing aliases will be overwritten.
const remark = 'remark';
const res = await RongIMLib.setGroupRemark(groupId, remark);
// Ensure the group ID exists; otherwise, queries will fail and throw exceptions
console.info('Group alias setting result', res);

Query Group Alias

Use the getGroupsInfo method to query group information, which includes alias data.

Method

RongIMLib.getGroupsInfo(groupIds)

Parameters

Parameter	Type	Required	Description
groupIds	string[]	Yes	Array of group IDs (max 20 per query).

warning

Non-existent group IDs will return no data and may trigger console exceptions.

Example Code

// Required: Array of group IDs (max 20 per query).
const groupIds = ['group001']
const res = await RongIMLib.getGroupsInfo(groupIds);
// Ensure the group ID exists; otherwise, queries will fail and throw exceptions
console.info('Group alias', res[0].remark);