Group Join Management

This document provides guidance for developers on how to use RC IM iOS IMLib SDK to implement features including actively joining groups, inviting users to join groups, users accepting or rejecting group invitations, and administrators approving or rejecting group join requests.

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.

Group Join Management

Group join management includes: actively joining groups, inviting users to join groups, users accepting or rejecting group invitations, and administrators approving or rejecting group join requests.

tip

For group join permission configuration, refer to Group Management. For group permission queries, refer to Group Query.

Actively Joining a Group

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

The result is affected by the group's join permission (joinPermission) parameter:

• When join permission is "Requires group owner/administrator approval":
  • After successful API call, processCode will return RC_GROUP_JOIN_GROUP_NEED_MANAGER_ACCEPT (25424), indicating that approval from the group owner or administrator is required. Both the requester and group owner/administrator will receive the onGroupApplicationEvent event callback.
• When join permission is "No approval required":
  • After successful API call, processCode will return RC_SUCCESS (0), indicating successful group join. Both the requester and all group members will receive the onGroupOperation event callback with operation type RCGroupOperationJoin.

Sample Code

[[RCCoreClient sharedCoreClient] joinGroup:@"groupId" success:^(RCErrorCode processCode) {
    // Join successful
} error:^(RCErrorCode errorCode) {
    // Join failed
}];

Inviting Others to Join a Group

This feature is affected by the group invite role permission invitePermission. Only users with permission can call the inviteUsersToGroup method to invite others to join the group.

API Prototype

- (void)inviteUsersToGroup:(NSString *)groupId
                   userIds:(NSArray<NSString *> *)userIds
                   success:(void (^)(RCErrorCode processCode))successBlock
                     error:(void (^)(RCErrorCode errorCode))errorBlock;

Parameter Description

Parameter	Type	Description
groupId	NSString	The targetId of the group.
userIds	NSArray	List of user userIds, maximum 30 at a time.
successBlock	Block	Success callback.
errorBlock	Block	Failure callback.

Sample Code

// User IDs to invite to the group
NSArray *userIds = @[@"userId1", @"userId2"];

[[RCCoreClient sharedCoreClient] inviteUsersToGroup:@"groupId" userIds:userIds success:^(RCErrorCode processCode) {
    // Invite successful
} error:^(RCErrorCode errorCode) {
    // Invite failed
}];

The group join invitation process is influenced by three factors:

1. Join Permission (joinPermission): Whether group owner/administrator approval is required.
2. Inviter Role (role): Whether the inviter is a group owner/administrator or a regular member.
3. Invitee Handling Permission (inviteHandlePermission): Whether invitee consent is required to join the group.

Specific Rules

tip

The table below assumes the group's invite permission (invitePermission) is RCGroupOperationPermissionEveryone, meaning anyone can invite others to join the group.

In development, you can set different permissions as needed.

Join Permission	Inviter Role	Invitee Approval	Event Flow
Requires owner/admin approval	Regular member	Required	Flow A
		Not required	Flow B
	Owner or admin	Required	Flow C
		Not required	Flow D
No owner/admin approval required	Any role	Required	Flow C
		Not required	Flow D

Event Flows

Flow A

Permission description:

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

1. After sending invitation, success callback's processCode returns RC_GROUP_JOIN_GROUP_NEED_MANAGER_ACCEPT (25424), indicating owner/admin approval is needed. Inviter and owner/admin receive onGroupApplicationEvent callback.
2. After owner/admin calls acceptGroupApplication to approve, inviter, owner/admin, and invitee receive onGroupApplicationEvent callback.
3. After invitee calls acceptGroupInvite to approve, inviter, owner/admin, and invitee receive onGroupApplicationEvent callback. All group members receive onGroupOperation callback with operation type RCGroupOperationJoin.

Flow B

Permission description:

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

1. After sending invitation, success callback's processCode returns RC_GROUP_JOIN_GROUP_NEED_MANAGER_ACCEPT (25424), indicating owner/admin approval is needed. Inviter and owner/admin receive onGroupApplicationEvent callback.
2. After owner/admin calls acceptGroupApplication to approve, invitee joins group successfully. Inviter and owner/admin receive onGroupApplicationEvent callback. All group members receive onGroupOperation callback with operation type RCGroupOperationJoin.

Flow C

Permission description:

• Any role (owner, admin or regular member) invites others, no owner/admin approval needed, requires invitee approval.

1. After sending invitation, success callback's processCode returns RC_GROUP_NEED_INVITEE_ACCEPT (25427), indicating invitee approval is needed. Inviter and invitee receive onGroupApplicationEvent callback.
2. After invitee calls acceptGroupInvite to approve, inviter and invitee receive onGroupApplicationEvent callback. All group members receive onGroupOperation callback with operation type RCGroupOperationJoin.

Flow D

Permission description:

• Owner/admin invites others, requires owner/admin approval, no invitee approval needed.
• Any role (owner, admin or regular member) invites others, no owner/admin approval needed, no invitee approval needed.

1. After sending invitation, success callback's processCode returns RC_SUCCESS (0), indicating successful invitation. Invitee joins group directly, all group members receive onGroupOperation callback with operation type RCGroupOperationJoin.

Handling Group Invitations

Accepting Group Invitation

After receiving a group invitation, users can call the acceptGroupInvite method to accept the invitation.

API Prototype

- (void)acceptGroupInvite:(NSString *)groupId
                inviterId:(NSString *)inviterId
                  success:(void (^)(void))successBlock
                    error:(void (^)(RCErrorCode errorCode))errorBlock;

Parameter Description

Parameter	Type	Description
groupId	NSString	The targetId of the group.
inviterId	NSString	The userId of the inviter.
successBlock	Block	Success callback.
errorBlock	Block	Failure callback.

Sample Code

// Group ID
NSString *groupId = @"groupId";
// Inviter ID
NSString *inviterId = @"inviterId";

[[RCCoreClient sharedCoreClient] acceptGroupInvite:groupId inviterId:inviterId success:^{
    // Successfully accepted invitation 
} error:^(RCErrorCode errorCode) {
    // Failed to accept invitation
}];

Rejecting Group Invitation

// Group ID
NSString *groupId = @"groupId";
// Inviter ID
NSString *inviterId = @"inviterId";
// Rejection reason (optional)
NSString *reason = @"reason";

[[RCCoreClient sharedCoreClient] refuseGroupInvite:groupId inviterId:inviterId reason:reason success:^{
    // Successfully rejected invitation
} error:^(RCErrorCode errorCode) {
    // Failed to reject invitation
}];


### Group Owner or Administrator Handling Join Requests

Group application processing is valid for 7 days. The RC service stores application data for up to 7 days, after which a new application must be submitted.


#### Approving Group Join Requests

Group owners or administrators can call the `acceptGroupApplication` method to approve group join requests.


- For user-initiated join requests, pass the applicant's ID in `applicantId` and set `inviterId` to `nil` or `@""`.


- For invitation-based join requests, pass the applicant's ID in `applicantId` and the inviter's ID in `inviterId`.


#### Method Prototype
```objc


- (void)acceptGroupApplication:(NSString *)groupId
                     inviterId:(nullable NSString *)inviterId
                   applicantId:(NSString *)applicantId
                       success:(void (^)(RCErrorCode processCode))successBlock
                         error:(void (^)(RCErrorCode errorCode))errorBlock;


#### Parameter Description

| **Parameter** | **Type** | **Description** |
| ------- | --------|------------------------------------------ |
| groupId      | NSString| The targetId of the group.|
| inviterId      | NSString| The userId of the inviter (optional). Required for invitation-based requests; set to nil for user-initiated requests.|
| applicantId      | NSString| The userId of the applicant.|
| successBlock  | Block | Success callback. |
| errorBlock | Block | Failure callback. |


##### Example Code

```objc
// Group ID
NSString *groupId = @"groupId";
// Inviter ID (required for invitation-based requests, nil for user-initiated requests)
NSString *inviterId = @"inviterId";
// Applicant ID
NSString *applicantId = @"applicantId";

[[RCCoreClient sharedCoreClient] acceptGroupApplication:groupId inviterId:inviterId applicantId:applicantId success:^(RCErrorCode processCode) {
    // Approval successful
} error:^(RCErrorCode errorCode) {
    // Approval failed
}];
After successful invocation, the `processCode` in the callback is affected by the group's invitee handling permission ([inviteHandlePermission]):


- When invitee approval is required, `processCode` returns `RC_GROUP_NEED_INVITEE_ACCEPT` (25427), indicating the invitee must approve before joining. The invitee receives an `onGroupApplicationEvent` callback.


- When no invitee approval is needed, `processCode` returns `RC_SUCCESS` (0), indicating the invitee has successfully joined. All group members receive an `onGroupOperation` callback for the join event.


#### Rejecting Group Join Requests

Group owners or administrators can call the `refuseGroupApplication` method to reject group join requests.


- For user-initiated join requests, pass the applicant's ID in `applicantId` and set `inviterId` to `nil` or `@""`.


- For invitation-based join requests, pass the applicant's ID in `applicantId` and the inviter's ID in `inviterId`.


#### Method Prototype
```objc


- (void)refuseGroupApplication:(NSString *)groupId
                     inviterId:(nullable NSString *)inviterId
                   applicantId:(NSString *)applicantId
                        reason:(nullable NSString *)reason
                       success:(void (^)(void))successBlock
                         error:(void (^)(RCErrorCode errorCode))errorBlock;


#### Parameter Description

| **Parameter** | **Type** | **Description** |
| ------- | --------|------------------------------------------ |
| groupId      | NSString| The targetId of the group.|
| inviterId      | NSString| The userId of the inviter (optional). Required for invitation-based requests; set to nil for user-initiated requests.|
| applicantId      | NSString| The userId of the applicant.|
| reason      | NSString| Rejection reason.|
| successBlock  | Block | Success callback. |
| errorBlock | Block | Failure callback. |


##### Example Code

```objc
// Group ID
NSString *groupId = @"groupId";
// Applicant ID
NSString *applicantId = @"applicantId";
// Inviter ID (required for invitation-based requests, nil for user-initiated requests)
NSString *inviterId = @"inviterId";
// Rejection reason (optional)
NSString *reason = @"reason";

[[RCCoreClient sharedCoreClient] refuseGroupApplication:groupId inviterId:inviterId applicantId:applicantId reason:reason success:^{
    // Rejection successful
} error:^(RCErrorCode errorCode) {
    // Rejection failed
}];


## Paginated Retrieval of Group Application List

You can call the `getGroupApplications` method to retrieve group applications in pages. Group application processing is valid for 7 days. The RC service stores application data for up to 7 days, after which a new application must be submitted.


#### Method Prototype
```objc


- (void)getGroupApplications:(RCPagingQueryOption *)option
                  directions:(NSArray<NSNumber *> *)directions
                      status:(NSArray<NSNumber *> *)status
                     success:(void (^)(RCPagingQueryResult<RCGroupApplicationInfo *> *result))successBlock
                       error:(void (^)(RCErrorCode errorCode))errorBlock;


#### Parameter Description

| **Parameter** | **Type** | **Description** |
| --- | --- | --- |
| option | RCPagingQueryOption | Query options including page token (optional, returns first page if empty), items per page (max 200), and sort order (default descending) |
| directions | NSArray\<NSNumber *\> | Array of application directions [RCGroupApplicationDirection] |
| status | NSArray\<NSNumber *\> | Array of status types [RCGroupApplicationStatus] |
| successBlock | Block| Success callback returning [RCGroupApplicationInfo] array (total count not supported) |
| errorBlock | Block | Failure callback |


#### Example Code

```objc


- (void)getGroupApplications:(NSString *)pageToken {
    // Query options
    RCPagingQueryOption *option = [[RCPagingQueryOption alloc] init];
    // Page token (nil for first page)
    option.pageToken = pageToken;
    // Items per page
    option.count = 20;
    // Default NO for descending by operation time, YES for ascending
    option.order = NO;
    // Application directions
    NSArray<NSNumber *> *directions = @[@(RCGroupApplicationDirectionInvitationReceived)];
    // Status types
    NSArray<NSNumber *> *status = @[@(RCGroupApplicationStatusManagerUnHandled)];

    [[RCCoreClient sharedCoreClient] getGroupApplications:option directions:directions status:status success:^(RCPagingQueryResult<RCGroupApplicationInfo *> * _Nonnull result) {
        // Retrieval successful
        if (result.pageToken.length > 0) {
            // When pageToken exists, fetch next page
            [self getGroupApplications:result.pageToken];
        } else {
            // Completed, no more data
        }
    } error:^(RCErrorCode errorCode) {
        // Failed
    }];
}