Join group

This document guides developers on how to use RongCloud's Instant Messaging Web IMLib SDK to implement the following group-related features:

• Actively applying to join groups
• Inviting users to join groups
• Users handling group invitations (accept or reject)
• Group administrators handling join requests (approve or reject)
• Paginated retrieval of group application lists

tip

This feature is supported starting from version 5.12.0.

Service Activation

The information hosting service is enabled by default, and you can use this feature directly.

User Application/Invitation Events and Result Callbacks

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

Example 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, users handling group invitations, and group owners/administrators handling join requests.

Actively Join a Group

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

tip

The interface call result is affected by the group's GroupJoinPermission settings, as follows:

1. Requires group owner/administrator approval: After a successful interface call, processCode returns 25424, indicating that group owner/administrator approval is required. The applicant and group owner/administrator will receive the Events.GROUP_APPLICATION_EVENT callback.

2. No approval required: After a successful interface call, processCode returns 0, indicating successful group joining. The applicant and all group members will receive the Events.GROUP_OPERATION callback, where operation=1 (GroupOperation.JOIN).

3. No one is allowed to join: The joinGroup interface cannot be used to join the group.

Interface

RongIMLib.joinGroup(groupId)

Parameter Description

Parameter	Type	Required	Description
groupId	string	Yes	Group ID.

Example Code

// Required, maximum length of 64 characters. Supports combinations of uppercase/lowercase letters and numbers
const groupId = 'group001';
const res = await RongIMLib.joinGroup(groupId);
console.info('Group join result', res);

Invite Others to Join a Group

Inviting others to join a group is controlled by the group's invitation permission GroupOperationPermission. Only users with the appropriate permissions can initiate invitations.

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

Interface

RongIMLib.inviteUsersToGroup(groupId, userIds)

Parameter Description

Parameter	Type	Required	Description
groupId	string	Yes	Group ID.
userIds	string[]	Yes	Array of user IDs, supporting up to 30 users.

Example Code

const groupId = 'group001'; // Group ID
const userIds = ['user001', 'user002']; // Array of user IDs, supporting up to 30 users

const res = await RongIMLib.inviteUsersToGroup(groupId, userIds);
console.info('Result of inviting users to join group', res);

Invitation process is affected by the following factors:

1. Join permission (GroupJoinPermission): Whether group owner/administrator approval is required.
2. Inviter role (GroupOperationPermission): Whether the inviter is a group owner/administrator or a regular user.
3. Invitee handling permission (GroupInviteHandlePermission): Whether invitee consent is required to join the group.

Invitation Rules

tip

The table below assumes the group's invitation permission GroupOperationPermission is set to Everyone, meaning all members can invite others to join the group.

Developers can set different permissions based on actual requirements.

Join Permission	Inviter Role	Invitee Approval	Event Flow
Requires group owner/admin approval	Regular user	Required	Flow A
		Not required	Flow B
	Group owner/admin	Required	Flow C
		Not required	Flow D
No group owner/admin approval required	All roles	Required	Flow C
		Not required	Flow D

Event Flows

Flow A

Regular user invites others, requires group owner/admin approval, and invitee consent.

1. After sending the invitation, the success callback's code returns 25424, indicating group owner/admin approval is pending. The inviter and group owner/admin receive the Events.GROUP_APPLICATION_EVENT callback.
2. After group owner/admin approval, the inviter, group owner/admin, and invitee receive the Events.GROUP_APPLICATION_EVENT callback.
3. After invitee consent, the inviter, group owner/admin, and invitee receive the Events.GROUP_APPLICATION_EVENT callback. All group members receive the group operation Events.GROUP_OPERATION callback, where operation value is 1, corresponding to enum GroupOperation.JOIN.

Flow B

• Regular user invites others, requires group owner/admin approval, no invitee consent needed.

1. After sending the invitation, the success callback's code returns 25424, indicating group owner/admin approval is pending. The inviter and group owner/admin receive the Events.GROUP_APPLICATION_EVENT callback.
2. After group owner/admin approval, the invitee successfully joins the group. The inviter and group owner/admin receive the Events.GROUP_APPLICATION_EVENT callback. All group members receive the Events.GROUP_OPERATION callback, where operation value is 1, corresponding to enum GroupOperation.JOIN.

Flow C

• Any role user invites others, no group owner/admin approval needed, requires invitee consent.

1. After sending the invitation, the success callback's code returns 25427, indicating invitee consent is required. The inviter and invitee receive the Events.GROUP_APPLICATION_EVENT callback.
2. After invitee consent, the inviter and invitee receive the Events.GROUP_APPLICATION_EVENT callback. All group members receive the Events.GROUP_OPERATION callback, where operation value is 1, corresponding to enum GroupOperation.JOIN.

Flow D

• Group owner/admin invites others, requires group owner/admin approval, no invitee consent needed.
• Any role user invites others, no group owner/admin approval needed, no invitee consent needed.

1. After sending the invitation, the success callback's code returns 0, indicating successful invitation. The invitee directly joins the group, and all group members receive the Events.GROUP_OPERATION callback, where operation value is 1, corresponding to enum GroupOperation.JOIN.

User Handling of Group Invitations

Accept Group Invitation

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

Interface

RongIMLib.acceptGroupInvite(groupId, inviterId)

Parameter Description

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);

Reject Group Invitation

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

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 rejection reason, limited to 128 characters

Example Code

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

Group Owner or Administrator Handling Join Requests

Approve Join Request

When a group owner or administrator receives a join request, they can call the acceptGroupApplication method to approve the user's request to join the group.

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 invitation-based requests; can be omitted for direct join requests.

tip

• For direct join requests, provide the applicant's ID in applicantId and leave inviterId empty or pass an empty string ''.
• For invitation-based requests, provide the applicant's ID in applicantId and the inviter's 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 user join request', res);

Code Explanation

The returned code is controlled by group invitation permissions (GroupInviteHandlePermission):

1. Requires invitee confirmation: Returns 25427, indicating the applicant needs to confirm. The invitee will receive the Events.GROUP_APPLICATION_EVENT callback.
2. No invitee confirmation required: Returns 0, indicating successful approval. Group members will receive the Events.GROUP_OPERATION "join group" event notification.

Reject Join Request

When a group owner or administrator receives a join request, 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 invitation-based requests; can be omitted for direct join requests.
reason	string	No	Rejection reason, optional, limited to 128 characters

tip

• For direct join requests, provide the applicant's ID in applicantId and leave inviterId empty or pass an empty string ''.
• For invitation-based requests, provide the applicant's ID in applicantId and the inviter's 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 join requests
const reason = 'Does not meet group requirements'; // Optional rejection reason
const res = await RongIMLib.refuseGroupApplication(groupId, applicantId, inviterId, reason);
console.info('Result of rejecting user join request', res);

Paginated Retrieval of Group Application List

Call the getGroupApplications method to paginate through the current group's application records.

tip

• Application records are valid for 7 days. Data older than 7 days is automatically cleared and requires reapplication.
• The IPagingQueryResult structure returned on Web platforms currently does not include the totalCount field.

Interface

RongIMLib.getGroupApplications(option, directions, status)

Parameters

Parameter	Type	Required	Description
option	IPagingQueryOption	Yes	Pagination parameters, with a maximum of 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('Result of retrieving group request list', res);