Friend Management

This document guides developers on how to use RC's instant messaging iOS IMLib SDK to implement friend-related functions including adding friends, deleting friends, viewing friend lists, and managing friend relationships.

tip

Friend management features are 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.

Friend Event Subscription

To receive notifications for friend additions/deletions, friend request status changes, complete friend list clearing, and multi-device sync of friend information changes, you need to set up a friend event subscription delegate after initializing the IMLib SDK but before establishing the connection. Implement the relevant delegate methods from the [RCFriendEventDelegate] protocol.

Call addFriendEventDelegate to set up the friend event listener. To stop receiving friend events, call removeFriendEventDelegate to remove the listener.

tip

In User Profile Hosting service, SDK notification callbacks triggered by friend operations are considered status notifications. Therefore, regardless of whether your app implements friend event listeners, the server will synchronize status with the client SDK to ensure local friend relationship status remains up-to-date. These notifications will be counted in message distribution and downstream data statistics.

Sample Code

// Add friend event listener
[[RCCoreClient sharedCoreClient] addFriendEventDelegate:self];

// Remove friend event listener
[[RCCoreClient sharedCoreClient] removeFriendEventDelegate:self];

// -------- Callback Events ----------

// Friend addition callback
- (void)onFriendAdd:(NSString *)userId 
               name:(NSString *)name
        portraitUri:(NSString *)portraitUri
      directionType:(RCDirectionType)directionType
      operationTime:(long long)operationTime {
    
}

// Friend deletion callback
- (void)onFriendDelete:(NSArray<NSString *> *)userIds 
         directionType:(RCDirectionType)directionType
         operationTime:(long long)operationTime {
    
}

// Friend request status change callback
- (void)onFriendApplicationStatusChanged:(NSString *)userId 
                         applicationType:(RCFriendApplicationType)applicationType
                       applicationStatus:(RCFriendApplicationStatus)status
                           directionType:(RCDirectionType)directionType
                           operationTime:(long long)operationTime
                                   extra:(NSString *)extra {
    
}

// Complete friend list clearing callback (Note: This operation can only be initiated by the server)
- (void)onFriendCleared:(long long)operationTime {
    
}

// Multi-device sync for friend information changes
- (void)onFriendInfoChangedSync:(NSString *)userId 
                         remark:(NSString *)remark
                     extProfile:(NSDictionary<NSString *,NSString *> *)extProfile
                  operationTime:(long long)operationTime {
    
}

Friend Online Status and Profile Changes

IMLib SDK automatically handles online status and profile changes between friends.
To receive change notifications, call addSubscribeEventDelegate after SDK initialization but before establishing the connection to set up the change event listener.

Subscription event changes should be processed according to [RCSubscribeType] subscription types:

RCSubscribeTypeFriendOnlineStatus represents friend online status.
RCSubscribeTypeFriendUserProfile represents friend profile changes.

tip

You must enable "Client-side Friend Profile Change Notifications" and "Client-side Friend Online Status Change Notifications" in the developer console to use this feature. Real-time notifications about friend online status and profile changes will be counted in one-to-one chat message distribution and downstream data statistics.

Sample Code

// Add subscription delegate
[[RCCoreClient sharedCoreClient] addSubscribeEventDelegate:self];

// Remove subscription delegate
// [[RCCoreClient sharedCoreClient] removeSubscribeEventDelegate:self];

// ---------- Event Callbacks ----------

// Event change callback
- (void)onEventChange:(NSArray<RCSubscribeInfoEvent *> *)subscribeEvents {
    // Check RCSubscribeInfoEvent's subscribeType:
    // RCSubscribeTypeFriendOnlineStatus for user status subscription events
    // RCSubscribeTypeFriendUserProfile for friend profile change events
}

// Subscription sync completion
- (void)onSubscriptionSyncCompleted:(RCSubscribeType)type {
    // Use type to distinguish subscription types:
    // RCSubscribeTypeFriendOnlineStatus for friend online status
    // RCSubscribeTypeFriendUserProfile for friend profile changes
}

Friend Operations

Add Friend

Call addFriend to add a specified user as friend by their userId. You can include additional information in the extra parameter that will be sent to the user being added.
Use RC's User Search feature to obtain user userIds.

tip

A single user can add up to 3000 friends.

Sample Code

// Target user's userId
NSString *userId = @"userId1";
// Currently only mutual friends are supported (may support other types later)
RCDirectionType directionType = RCDirectionTypeBoth;
// Additional info for friend request (max 128 characters)
NSString *extra = @"Friend request";
[[RCCoreClient sharedCoreClient] addFriend:userId
                                directionType:directionType
                                        extra:extra
                                    success:^(RCErrorCode processCode) {
    // Friend request successful
    if (processCode == RC_SUCCESS) {
        // Friend added successfully
    } else {
        // Waiting for friend confirmation
    }
} error:^(RCErrorCode errorCode) {
    // Friend request failed
}];

Set Friend Addition Permission

Use setFriendAddPermission to configure the current user's friend addition permission. If not set, the App Key's default permission will apply.

Friend Addition Permission Notes

The App Key's default user permission is Require user consent for friend additions.
User-specific permission settings override App Key defaults. If a user hasn't set their own permission, the App Key's setting will apply.

Friend Addition Permission `RCFriendAddPermission` Enumeration

Enum Value	Description
RCFriendAddPermissionFree	Anyone can add as friend directly
RCFriendAddPermissionNeedVerify	Requires user consent for friend addition
RCFriendAddPermissionNoOneAllowed	No one is allowed to add as friend

Sample Code

// Set friend addition permission to require user consent
RCFriendAddPermission permission = RCFriendAddPermissionNeedVerify;
    
// Configure friend addition permission
[[RCCoreClient sharedCoreClient] setFriendAddPermission:permission success:^{
    // Success
} error:^(RCErrorCode errorCode) {
    // Failure
}];

Get Friend Addition Permission

Use getFriendAddPermission to retrieve the current user's friend addition permission.

Sample Code

// Get friend addition permission
[[RCCoreClient sharedCoreClient] getFriendAddPermission:^(RCFriendAddPermission permission) {
    // Success
} error:^(RCErrorCode errorCode) {
    // Failure
}];

Different permission settings result in these two workflows

Users A and B set up friend event listeners via addFriendEventDelegate.
User B configures friend addition permission as "Anyone can add as friend directly" using setFriendAddPermission (see [RCFriendAddPermission]).
User A calls addFriend to request adding B as friend. The success callback returns RC_SUCCESS (0) in processCode, indicating direct friend addition. Both users receive the friend addition callback [onFriendAdd].

Users A and B set up friend event listeners via addFriendEventDelegate.
User B configures friend addition permission as "Requires user consent" using setFriendAddPermission (see [RCFriendAddPermission]).
User A calls addFriend to request adding B as friend. The success callback returns RC_FRIEND_NEED_ACCEPT (25461) in processCode, indicating pending approval. Both users receive the friend request status callback [onFriendApplicationStatusChanged] (with status parameter RCFriendApplicationStatusUnHandled).
Upon receiving [onFriendApplicationStatusChanged], User B can choose to:
- Accept via acceptFriendApplication, triggering [onFriendAdd] callback for both users upon success.
- Reject via refuseFriendApplication, triggering [onFriendApplicationStatusChanged] callback for both users (status parameter RCFriendApplicationStatusRefused).

Remove Friends

Use deleteFriends to remove multiple friend relationships. Successful removal triggers the [onFriendDelete] callback for both parties.

Maximum 100 friends per operation.

Sample Code

// Friend user ID list
NSArray *userIds = @[@"userId1", @"userId2"];
// Currently only supports RCDirectionTypeBoth
RCDirectionType directionType = RCDirectionTypeBoth;

// Remove friend relationships
[[RCCoreClient sharedCoreClient] deleteFriends:userIds directionType:directionType success:^{
    // Success
} error:^(RCErrorCode errorCode) {
    // Failure
}];

Check Friend Relationships

Use checkFriends to verify friend relationships (currently supports bidirectional verification only).

tip

Maximum 20 users per check.

Sample Code

// Friend user ID list
NSArray *userIds = @[@"userId1", @"userId2"];
// Currently only supports RCDirectionTypeBoth
RCDirectionType directionType = RCDirectionTypeBoth;

// Check friend relationships
[[RCCoreClient sharedCoreClient] checkFriends:userIds
                                directionType:directionType
                                        success:^(NSArray<RCFriendRelationInfo *> *friendRelations) {
    // Success
} error:^(RCErrorCode errorCode) {
    // Failure
}];

Friend Request Operations

Paginated Friend Request List

Use getFriendApplications to view all sent/received friend requests.

The success callback's result returns -1, indicating total count isn't supported.
Friend requests expire after 7 days. RC stores maximum 7 days of request data - expired requests require re-initiation.

Interface Prototype

- (void)getFriendApplications:(RCPagingQueryOption *)option
                        types:(NSArray<NSNumber *> *)types
                       status:(NSArray<NSNumber *> *)status
                      success:(void (^)(RCPagingQueryResult<RCFriendApplicationInfo *> *result))successBlock
                        error:(void (^)(RCErrorCode errorCode))errorBlock;

Parameters

Type: [RCPagingQueryOption]

Parameter	Type	Description
pageToken	NSString	Pagination token. For initial fetch, pass nil or @"". If subsequent `result.pageToken` isn't @"", pass it to continue fetching until `pageToken` returns @"".
count	NSInteger	Items per page (max 100)
order	BOOL	Sort by request time (default NO = descending, YES = ascending)

Sample Code

// Query options
RCPagingQueryOption *option = [[RCPagingQueryOption alloc] init];
// Items per page
option.count = 20;
// Default NO = descending by request time, YES = ascending
option.order = NO;
// Request types (example: sent + received)
NSArray<NSNumber *> *types = @[@(RCFriendApplicationTypeSent), @(RCFriendApplicationTypeReceived)];
// Status types
NSArray<NSNumber *> *status = @[@(RCFriendApplicationStatusUnHandled)];


// Get friend applications
[[RCCoreClient sharedCoreClient] getFriendApplications:option
                                                    types:types
                                                status:status
                                                success:^(RCPagingQueryResult<RCFriendApplicationInfo *> *result) {
    // Success
    if (result.pageToken.length > 0) {
        // Continue fetching next page
        [self getFriendApplications:result.pageToken];
    } else {
        // Completed, no more data
        for (RCFriendApplicationInfo *info in result.data) {
            if (info.applicationType == RCFriendApplicationTypeSent) {
                // Sent application
            }
            if (info.applicationType == RCFriendApplicationTypeReceived) {
                // Received application
            }
            if (info.applicationStatus == RCFriendApplicationStatusUnHandled) {
                // Pending application
            }
        }
    }
} error:^(RCErrorCode errorCode) {
    // Failed
}];

Accept friend request

After receiving a friend request, call acceptFriendApplication to accept it. Upon success, both parties will trigger the [onFriendAdd] callback.

Sample Code

 // Friend user ID
NSString *userId = @"userId1";

// Accept friend application
[[RCCoreClient sharedCoreClient] acceptFriendApplication:userId success:^{
    // Success
} error:^(RCErrorCode errorCode) {
    // Failed
}];

Reject friend request

After receiving a friend request, call refuseFriendApplication to reject it. Upon success, both parties will trigger the [onFriendApplicationStatusChanged] callback (with status parameter set to RCFriendApplicationStatusRefused).

Sample Code

// Friend user ID
NSString *userId = @"userId1";

// Reject friend application
[[RCCoreClient sharedCoreClient] refuseFriendApplication:userId success:^{
    // Success
} error:^(RCErrorCode errorCode) {
    // Failed
}];

Friend information management

Get friend list

Use getFriends to retrieve the current user's friend list.

Sample Code

// Query direction (currently only bidirectional friends supported)
RCQueryFriendsDirectionType directionType = RCQueryFriendsDirectionTypeBoth;

// Get friend list
[[RCCoreClient sharedCoreClient] getFriends:directionType success:^(NSArray<RCFriendInfo *> *friendInfos) {
    // Success
} error:^(RCErrorCode errorCode) {
    // Failed
}];

Set friend information

Use setFriendInfo to configure friend remarks and extended information.

tip

You must first configure custom attributes in the RC Console Friend Custom Attributes section before using extended information keys. Otherwise, setting will fail. Maximum 10 extended information keys supported.
After successful modification, other logged-in devices will receive the [onFriendInfoChangedSync] callback.
By default, profile modifications aren't subject to moderation. To enable moderation, go to [Console] > App Configuration > Security & Moderation > IM & RTC Moderation > IM Information Hosting Configuration and enable the required content moderation.

Sample Code

// Friend user ID
NSString *userId = @"userId1";
// Remark (max 64 chars, empty string clears remark)
NSString *remark = @"Remark";
// Extended information (set value to empty string @"" to clear)
NSDictionary *extProfile = @{@"key1": @"value1", @"key2": @"value2"};

// Set friend information
[[RCCoreClient sharedCoreClient] setFriendInfo:userId
                                            remark:remark
                                        extProfile:extProfile
                                        success:^{
    // Success
} error:^(RCErrorCode errorCode, NSArray<NSString *> * _Nullable errorKeys) {
    // Failed
    // When errorCode == RC_SERVICE_INFORMATION_AUDIT_FAILED, errorKeys returns rejected attribute names (e.g. remark)
}];

Get friend information by userId

Use getFriendsInfo to retrieve friend information by userId.
Maximum 100 users per query.

Sample Code

// Friend user ID list
NSArray *userIds = @[@"userId1", @"userId2"];

// Get friend information
[[RCCoreClient sharedCoreClient] getFriendsInfo:userIds success:^(NSArray<RCFriendInfo *> *friendInfos) {
    // Success
} error:^(RCErrorCode errorCode) {
    // Failed
}];

Search friends by nickname

Use searchFriendsInfo to search friends by nickname.

Searches first match against friend remarks (remark), then friend names (name). Returns results if either field matches.

Sample Code

// Nickname keyword (required, max 64 chars)
NSString *name = @"name";

// Search friend information
[[RCCoreClient sharedCoreClient] searchFriendsInfo:name success:^(NSArray<RCFriendInfo *> *friendInfos) {
    // Success
} error:^(RCErrorCode errorCode) {
    // Failed
}];

icationstatus:directiontype:operationtime:extra:)?language=objc
[onFriendDelete]: https://doc.rongcloud.cn/apidoc/imlibcore-ios/latest/en_US/documentation/rongimlibcore/rcfriendeventdelegate/onfrienddelete(_:directiontype:operationtime:)?language=objc
[onFriendInfoChangedSync]: https://doc.rongcloud.cn/apidoc/imlibcore-ios/latest/en_US/documentation/rongimlibcore/rcfriendeventdelegate/onfriendinfochangedsync(_:remark:extprofile:operationtime:)?language=objc
[RCPagingQueryResult]: https://doc.rongcloud.cn/apidoc/imlibcore-ios/latest/en_US/documentation/rongimlibcore/rcpagingqueryresult?language=objc

IMLib

Global Chat UIKit

push notification

IMLib

Global Chat UIKit

Chat Server

Chat Server SDK

Enabling the Service​

Friend Event Subscription​

Sample Code​

Friend Online Status and Profile Changes​

Sample Code​

Friend Operations​

Add Friend​

Sample Code​

Set Friend Addition Permission​

Friend Addition Permission Notes​

Friend Addition Permission RCFriendAddPermission Enumeration​

Sample Code​

Get Friend Addition Permission​

Sample Code​

Different permission settings result in these two workflows​

Scenario 1: Friend addition doesn't require consent​

Scenario 2: Friend addition requires consent​

Remove Friends​

Sample Code​

Check Friend Relationships​

Sample Code​

Friend Request Operations​

Paginated Friend Request List​

Interface Prototype​

Parameters​

Sample Code​

Accept friend request​

Sample Code​

Reject friend request​

Sample Code​

Friend information management​

Get friend list​

Sample Code​

Set friend information​

Sample Code​

Get friend information by userId​

Sample Code​

Search friends by nickname​

Sample Code​

Enabling the Service

Friend Event Subscription

Sample Code

Friend Online Status and Profile Changes

Sample Code

Friend Operations

Add Friend

Sample Code

Set Friend Addition Permission

Friend Addition Permission Notes

Friend Addition Permission `RCFriendAddPermission` Enumeration

Sample Code

Get Friend Addition Permission

Sample Code

Different permission settings result in these two workflows

Scenario 1: Friend addition doesn't require consent

Scenario 2: Friend addition requires consent

Remove Friends

Sample Code

Check Friend Relationships

Sample Code

Friend Request Operations

Paginated Friend Request List

Interface Prototype

Parameters

Sample Code

Accept friend request

Sample Code

Reject friend request

Sample Code

Friend information management

Get friend list

Sample Code

Set friend information

Sample Code

Get friend information by userId

Sample Code

Search friends by nickname

Sample Code