Join group

This document guides developers on how to implement the following group-related features using RC IM Web IMLib SDK:

• Actively apply to join groups
• Invite users to join groups
• Handle group join invitations (accept or reject)
• Group administrators handle join requests (approve or reject)
• Paginated retrieval of group application lists

tip

This feature is supported starting from version 5.12.0.

Enabling the Service

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

User Application/Invitation Events and Result Callbacks

Users can actively call the joinGroup interface to apply for group membership, or be invited by existing members through the inviteUsersToGroup interface. Related application/invitation events and their processing results can be monitored via the Events.GROUP_APPLICATION_EVENT event, which returns data of type IGroupApplicationInfo.

Sample Code

RongIMLib.addEventListener(Events.GROUP_APPLICATION_EVENT, (data) => {
  console.log('User application/invitation events and result callbacks', data);
});

Group Join Management

Group join management includes: actively joining groups, inviting others to join groups, handling join invitations, and administrators processing join requests.

Actively Join Group

You can call the joinGroup method to actively apply to join a specified group.

tip

The interface result is affected by the group's GroupJoinPermission settings:

1. Requires Group Owner/Admin Approval: When successful, processCode returns 25424, indicating pending approval. Both the applicant and group administrators will receive the Events.GROUP_APPLICATION_EVENT callback.

2. No Approval Needed: When successful, processCode returns 0, indicating successful group join. The applicant and all group members will receive the Events.GROUP_OPERATION callback with operation=1 (GroupOperation.JOIN).

3. Closed Group: The joinGroup interface cannot be used to join the group.

Interface

RongIMLib.joinGroup(groupId)

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID.

Sample Code

// Required, max length 64 characters. Supports alphanumeric combinations
const groupId = 'group001';
const res = await RongIMLib.joinGroup(groupId);
console.info('Group join result', res);

Invite Users to Join Group

Group invitation operations are controlled by GroupOperationPermission. Only users with appropriate permissions can initiate invitations.

Users with invitation permissions can call inviteUsersToGroup to invite others to join the group.

Interface

RongIMLib.inviteUsersToGroup(groupId, userIds)

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID.
userIds	string[]	Yes	User ID array, supports up to 30 users.

Sample Code

const groupId = 'group001'; // Group ID
const userIds = ['user001', 'user002']; // User ID array (max 30 users)

const res = await RongIMLib.inviteUsersToGroup(groupId, userIds);
console.info('Group invitation result', res);

Invitation flow is affected by:

1. Join Permission (GroupJoinPermission): Whether group owner/admin approval is required.
2. Inviter Role (GroupOperationPermission): Whether inviter is group owner/admin or regular member.
3. Invitee Handling Permission (GroupInviteHandlePermission): Whether invitee consent is required.

Invitation Rules

tip

The table below assumes GroupOperationPermission is set to Everyone (all members can invite).

Actual implementations may use different permission settings.

Join Permission	Inviter Role	Invitee Approval	Event Flow
Requires owner/admin approval	Regular member	Required	Flow A
		Not required	Flow B
	Owner/Admin	Required	Flow C
		Not required	Flow D
No approval needed	All roles	Required	Flow C
		Not required	Flow D

Event Flows

Flow B

• Regular member invites others, requires owner/admin approval, no invitee approval needed.

1. After invitation, successful callback returns code 25424, indicating pending owner/admin approval. Inviter and administrators receive Events.GROUP_APPLICATION_EVENT callback.

2. After owner/admin approval, invitee successfully joins group. Inviter and administrators receive Events.GROUP_APPLICATION_EVENT callback. All group members receive Events.GROUP_OPERATION callback with operation value 1 (GroupOperation.JOIN).

3. After sending the invitation, the success callback returns code 25424, indicating pending approval from the group owner/administrator. The inviter and group owner/administrator will receive the Events.GROUP_APPLICATION_EVENT callback.

4. After the group owner/administrator approves, the invitee successfully joins the group. The inviter and group owner/administrator will receive the Events.GROUP_APPLICATION_EVENT callback. All group members will receive the Events.GROUP_OPERATION callback with the operation value 1, corresponding to the enum GroupOperation.JOIN.

Process C

• When any role invites others, no approval from the group owner/administrator is required, but approval from the invitee is needed.

1. After sending the invitation, the success callback returns code 25427, indicating the invitee must agree before joining the group. The inviter and invitee will receive the Events.GROUP_APPLICATION_EVENT callback.
2. After the invitee agrees, the inviter and invitee will receive the Events.GROUP_APPLICATION_EVENT callback. All group members will receive the Events.GROUP_OPERATION callback with the operation value 1, corresponding to the enum GroupOperation.JOIN.

Process D

• When the group owner/administrator invites others, approval from the group owner/administrator is required, but no approval from the invitee is needed.
• When any role invites others, no approval from the group owner/administrator or invitee is needed.

1. After sending the invitation, the success callback returns code 0, indicating the invitation was successful. The invitee will join the group directly, and all group members will receive the Events.GROUP_OPERATION callback with the operation value 1, corresponding to the enum GroupOperation.JOIN.

Handling Group Invitations

Accepting Group Invitations

When a user receives a group invitation, they can call the acceptGroupInvite method to join the specified group.

Interface

RongIMLib.acceptGroupInvite(groupId, inviterId)

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID
inviterId	string	Yes	User ID of the inviter

Example Code

const groupId = 'group001'; // Group ID
const inviterId = 'inviterId'; // User ID of the inviter
const res = await RongIMLib.acceptGroupInvite(groupId, inviterId);
console.info('Result of accepting group invitation', res);

Declining Group Invitations

When a user receives a group invitation, they can call the refuseGroupInvite method to decline the invitation.

Interface

RongIMLib.refuseGroupInvite(groupId, inviterId, reason)

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID
inviterId	string	Yes	User ID of the inviter
reason	string	No	Optional reason for declining (max 128 characters)

Example Code

const groupId = 'group001'; // Group ID
const inviterId = 'inviterId'; // User ID of the inviter
const reason = 'Not interested'; // Optional reason for declining
const res = await RongIMLib.refuseGroupInvite(groupId, inviterId, reason);
console.info('Result of declining group invitation', res);

Handling Group Applications

Approving Group Applications

When the group owner or administrator receives a group application, they can call the acceptGroupApplication method to approve the request.

Interface

RongIMLib.acceptGroupApplication(groupId, applicantId, inviterId)

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID
applicantId	string	Yes	User ID of the applicant
inviterId	string	No	User ID of the inviter. Optional—required for invited applications, omit for direct applications.

tip

• For direct applications, pass the applicant ID in applicantId and omit inviterId or pass an empty string ''.
• For invited applications, pass the applicant ID in applicantId and the inviter ID in inviterId.

Example Code

const groupId = 'group001'; // Group ID
const applicantId = 'applicantId'; // User ID of the applicant
const res = await RongIMLib.acceptGroupApplication(groupId, applicantId);
console.info('Result of approving group application', res);

Code Explanation

The returned code depends on group invitation permissions (GroupInviteHandlePermission):

1. Invitee approval required: Returns 25427, indicating the applicant must confirm. The invitee will receive the Events.GROUP_APPLICATION_EVENT callback.
2. No invitee approval required: Returns 0, indicating success. Group members will receive the Events.GROUP_OPERATION callback for "join group" notifications.

Rejecting Group Applications

When the group owner or administrator receives a group application, they can call the refuseGroupApplication method to reject the request.

Interface

RongIMLib.refuseGroupApplication(groupId, applicantId, inviterId, reason)

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Group ID
applicantId	string	Yes	User ID of the applicant
inviterId	string	No	User ID of the inviter. Optional—required for invited applications, omit for direct applications.
reason	string	No	Optional rejection reason (max 128 characters)

tip

• For direct applications, pass the applicant ID in applicantId and omit inviterId or pass an empty string ''.
• For invited applications, pass the applicant ID in applicantId and the inviter ID in inviterId.

Example Code

const groupId = 'group001'; // Group ID
const applicantId = 'applicantId'; // User ID of the applicant
const inviterId = 'inviterId'; // Optional—pass '' or undefined for direct applications
const reason = 'Does not meet group requirements'; // Optional rejection reason
const res = await RongIMLib.refuseGroupApplication(groupId, applicantId, inviterId, reason);
console.info('Result of rejecting group application', res);

Get group application list by page

Call the getGroupApplications method to query group application records by page.

tip

• Application records expire after 7 days and will be automatically cleared. New applications must be submitted.
• The IPagingQueryResult structure returned on Web platforms currently doesn't include the totalCount field.

Interface

RongIMLib.getGroupApplications(option, directions, status)

Parameters

Parameter	Type	Required	Description
option	IPagingQueryOption	Yes	Pagination parameters. Maximum 200 records per page
directions	GroupApplicationDirection	No	Group application direction (Electron only)
status	GroupApplicationStatus	No	Group application status (Electron only)

Example code

const option = {
    // Required, range 1-200
    count: 50,
}
const directions = [GroupApplicationDirection.ApplicationSent]; // Group request direction array
const status = [GroupApplicationStatus.JoinUnHandled]; // Group request status array
const res = await RongIMLib.getGroupApplications(option, directions, status);
console.info('Group request query result', res);