Friend Management

This document guides developers on how to use the RC Instant Messaging Android IMLib SDK to implement friend-related features including adding friends, deleting friends, viewing friend lists, and managing friends.

tip

This feature has been supported since version 5.12.0.

Service Activation

The User Profile Hosting service is enabled by default, allowing you to use this functionality directly.

Friend Event Subscription

To receive real-time notifications for friend additions/deletions, friend request status changes, complete friend list clearance, and multi-device synchronization of friend profile updates, you must set up a friend event listener FriendEventListener after initializing the IMLib SDK but before establishing the connection.

Call setFriendEventListener to configure the friend event listener. Pass null to stop receiving friend events.

tip

In the User Profile Hosting service, SDK notifications triggered by friend operations are considered status notifications. Regardless of whether the application implements the SDK event listener, the server will synchronize status updates with the SDK to maintain the latest friend relationship status. These operations will be counted in message distribution and downstream data statistics.

Sample Code

FriendEventListener friendEventListener = new FriendEventListener() {
    @Override
    public void onFriendAdd(DirectionType directionType, String userId, String name, String portraitUri, long operationTime) {
        // Friend addition callback
    }

    @Override
    public void onFriendDelete(DirectionType directionType, List<String> userIds, long operationTime) {
        // Friend deletion callback
    }

    @Override
    public void onFriendApplicationStatusChanged(String userId, FriendApplicationType applicationType, FriendApplicationStatus status, DirectionType directionType, long operationTime, String extra) {
        // Friend request status change callback
    }

    @Override
    public void onFriendCleared(long operationTime) {
        // Complete friend list clearance callback. Note: This operation can only be initiated by the server.
    }

    @Override
    public void onFriendInfoChangedSync(String userId, String remark, Map<String, String> extProfile, long operationTime) {
        // Multi-device synchronization callback for friend profile updates
    }
};
RongCoreClient.getInstance().setFriendEventListener(friendEventListener);

Friend Online Status and Profile Updates

The IMLib SDK automatically handles online status and profile updates between friends.
To receive change notifications, call addSubscribeEventListener to set up a change event listener after SDK initialization but before connection establishment.

Event subscription changes should be processed according to the SubscribeType:

• FRIEND_ONLINE_STATUS(3) indicates friend online status;
• FRIEND_USER_PROFILE(4) indicates friend profiles.

tip

You must enable "Client Friend Profile Change Notifications" and "Client Friend Online Status Change Notifications" in the developer console to use this feature. These notifications will be counted in one-to-one chat message distribution and downstream data statistics.

Sample Code

RongCoreClient.getInstance().addSubscribeEventListener(new OnSubscribeEventListener() {
    /**
     * @param subscribeEvents List of subscription events containing all changed events.
     * When a subscriber's status changes, SubscribeEvent.operationType has no value.
     * Subscription expiration does not trigger notifications - developers must monitor expiration times independently.
     * Note: Check the SubscribeType in SubscribeInfoEvent - FRIEND_ONLINE_STATUS indicates friend online status, FRIEND_USER_PROFILE indicates friend profiles.
     */
    @Override
    public void onEventChange(List<SubscribeInfoEvent> subscribeEvents) {

    }

    /**
     * Marks completion of subscription data synchronization. Called after subscription data is successfully synced to the device/system for subsequent processing.
     * Note: Check SubscribeType - FRIEND_ONLINE_STATUS indicates friend online status, FRIEND_USER_PROFILE indicates friend profiles.
     *
     * @param type Synchronization completion type. Determine the specific business completion based on this type.
     * @since 5.10.0
     */
    @Override
    public void onSubscriptionSyncCompleted(SubscribeEvent.SubscribeType type) {

    }

});

Friend Operations

Adding Friends

Call addFriend to add a specified user as a friend by their userId. The extra parameter allows sending additional information with the friend request to the recipient. Obtain user IDs using RC's User Search functionality.

tip

A user can add up to 3000 friends.

Sample Code

// Target user ID for friend addition
String userId = "user1";
// Add as bidirectional friend
DirectionType directionType = DirectionType.Both;
// Additional information for the friend request (max 128 characters)
String extra = "Friend request";
RongCoreClient.getInstance().addFriend(userId, directionType, extra, new IRongCoreCallback.ResultCallback<IRongCoreEnum.CoreErrorCode>() {
    @Override
    public void onSuccess(IRongCoreEnum.CoreErrorCode processCode) {
        // Friend request successful
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // Friend request failed
    }
});

Configuring Friend Addition Permissions

Use setFriendAddPermission to configure the current user's friend addition permissions. If unset, the AppKey's default permissions apply.

Permission Explanation

• The default AppKey permission is Require user consent for friend additions.
• User-configured permissions override AppKey defaults. If unset, AppKey permissions apply.

FriendAddPermission Enum Values

Enum Value	Description
Free	Anyone can add directly
NeedVerify	Require user consent
NoOneAllowed	Disallow all friend additions

Sample Code

// Set current permission to NeedVerify
FriendAddPermission permission = FriendAddPermission.NeedVerify;
RongCoreClient.getInstance().setFriendAddPermission(permission, new IRongCoreCallback.OperationCallback() {
    @Override
    public void onSuccess() {
        // Permission configuration successful
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // Permission configuration failed
    }
});

Retrieving Friend Addition Permissions

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

Sample Code

RongCoreClient.getInstance().getFriendAddPermission(new IRongCoreCallback.ResultCallback<FriendAddPermission>() {
    @Override
    public void onSuccess(FriendAddPermission permission) {
        // Permission retrieval successful
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // Permission retrieval failed
    }
});

Different permission configurations trigger two workflows

Scenario 1: Direct Friend Addition Without Consent

1. Users A and B call setFriendListener to configure friend event listeners.
2. User B sets friend addition permission to: Anyone can add directly (Free), see FriendAddPermission.
3. User A calls addFriend to request adding B as a friend. The onSuccess callback returns IRongCoreEnum.CoreErrorCode.SUCCESS(0), indicating direct friend addition. Both users receive the onFriendAdd callback.

Scenario 2: Friend Addition Requiring Consent

1. Users A and B call setFriendListener to configure friend event listeners.
2. User B sets friend addition permission to: Require user consent (NeedVerify), see FriendAddPermission.
3. User A calls addFriend to request adding B as a friend. The onSuccess callback returns IRongCoreEnum.CoreErrorCode.RC_FRIEND_NEED_ACCEPT(25461), indicating pending consent. Both users receive the onFriendApplicationStatusChanged callback with FriendApplicationStatus as UnHandled.
4. User B can then:
   • Call acceptFriendApplication to accept, triggering onFriendAdd for both users.
   • Call refuseFriendApplication to reject, triggering onFriendApplicationStatusChanged with FriendApplicationStatus as Refused.

Remove Friends

You can use deleteFriends to remove multiple friend relationships in bulk. Upon successful removal, both parties will receive the friend deletion callback onFriendDelete.

Each API call supports removing up to 100 friends.

Sample Code

// List of friend user IDs
List<String> userIds = new ArrayList<>();
userIds.add("user1");
userIds.add("user2");
userIds.add("user3");
// Remove bidirectional friends
DirectionType directionType = DirectionType.Both;
RongCoreClient.getInstance().deleteFriends(userIds, directionType, new IRongCoreCallback.OperationCallback() {
    @Override
    public void onSuccess() {
        // Friend removal successful
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // Friend removal failed
    }
});

Check Friend Relationships

You can use checkFriends to verify friend relationships, currently supporting only bidirectional friend checks.

tip

A maximum of 20 users can be checked per request.

Sample Code

// List of friend user IDs
List<String> userIds = new ArrayList<>();
userIds.add("user1");
userIds.add("user2");
userIds.add("user3");
// Check bidirectional friends
DirectionType directionType = DirectionType.Both;
RongCoreClient.getInstance().checkFriends(userIds, directionType, new IRongCoreCallback.ResultCallback<List<FriendRelationInfo>>() {
    @Override
    public void onSuccess(List<FriendRelationInfo> friendRelationInfos) {
        // Check successful callback
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // Check failed callback
    }
});

Friend Request Operations

Paginated Retrieval of Friend Request List

You can use getFriendApplications to view all sent and received friend request records.

• This API does not return the total count of requests.
• Friend requests remain valid for 7 days. Rong Cloud servers store request data for up to 7 days, after which new requests must be initiated.

tip

Paginated retrieval notes:

1. For initial retrieval, PagingQueryOption's pageToken requires no value (leaving unset, null, or "" has equivalent effect).
2. For subsequent pages, pass the pageToken returned in the PagingQueryResult from the initial call.
   • If not "", use this value to fetch the next page until pageToken returns "", indicating completion.
   • If "", no more pages exist or retrieval is complete. Passing "" will retrieve the first page again.

Sample Code

{
    // ...
    // Pagination parameter (null and "" are equivalent)
    String pageToken = "";
    getFriendApplications(pageToken);
    // ...
}

public void getFriendApplications(String pageToken) {
    // Pagination parameters
    PagingQueryOption option = new PagingQueryOption();
    // Set page size (1-100)
    option.setCount(20);
    // Pagination token
    option.setPageToken(pageToken);
    // Sort by operation time (true: ascending; false: descending)
    option.setOrder(false);
    // Query both sent and received friend requests
    FriendApplicationType[] types = new FriendApplicationType[]{FriendApplicationType.Sent, FriendApplicationType.Received};
    // Query unprocessed, accepted, and refused requests
    FriendApplicationStatus[] status = new FriendApplicationStatus[]{FriendApplicationStatus.UnHandled, FriendApplicationStatus.Accepted, FriendApplicationStatus.Refused};
    RongCoreClient.getInstance().getFriendApplications(option, types, status, new IRongCoreCallback.PageResultCallback<FriendApplicationInfo>() {
        @Override
        public void onSuccess(PagingQueryResult<FriendApplicationInfo> result) {
            if (!TextUtils.isEmpty(result.getPageToken())) {
                // Use returned pageToken for next page
                getFriendApplications(result.getPageToken());
            } else {
                // Retrieval complete
            }
        }

        @Override
        public void onError(IRongCoreEnum.CoreErrorCode e) {
            // Retrieval failed
        }
    });
}

Accept Friend Request

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

The request status FriendApplicationStatus in the friend application list will change to Accepted.

Sample Code

// Friend user ID
String userId = "user1";
RongCoreClient.getInstance().acceptFriendApplication(userId, new IRongCoreCallback.OperationCallback() {
    @Override
    public void onSuccess() {
        // Friend request accepted
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // Acceptance failed
    }
});

Reject Friend Request

Upon receiving a friend request, users may reject it by calling refuseFriendApplication.

After successful rejection, both parties will trigger onFriendApplicationStatusChanged with FriendApplicationStatus as Refused.

Sample Code

// Friend user ID
String userId = "user1";
RongCoreClient.getInstance().refuseFriendApplication(userId, new IRongCoreCallback.OperationCallback() {
    @Override
    public void onSuccess() {
        // Friend request rejected
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // Rejection failed
    }
});

Friend Information Management

Retrieve Friend List

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

Sample Code

// Query bidirectional friends
QueryFriendsDirectionType type = QueryFriendsDirectionType.Both;
RongCoreClient.getInstance().getFriends(type, new IRongCoreCallback.ResultCallback<List<FriendInfo>>() {
    @Override
    public void onSuccess(List<FriendInfo> friendInfos) {
        // Friend list retrieved
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // Retrieval failed
    }
});

Set Friend Information

Use setFriendInfo to configure a friend's alias and extended information.

tip

• Extended info keys must first be configured in Rong Cloud Console Friend Custom Attributes, otherwise setup fails. Maximum 10 extended keys supported.
• Upon successful modification, other logged-in devices will receive the multi-device sync callback onFriendInfoChangedSync.

Sample Code

// Friend user ID
String userId = "user1";
// Friend alias (max 64 chars). Empty value clears existing alias.
String remark = "user1's alias";
// Extended info (max 10 key-value pairs)
Map<String, String> extProfile = new HashMap<>();
extProfile.put("ext_key_1", "ext_value_1");
extProfile.put("ext_key_2", "ext_value_2");
RongCoreClient.getInstance().setFriendInfo(userId, remark, extProfile, new IRongCoreCallback.OperationCallback() {
    @Override
    public void onSuccess() {
        // Friend info updated
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // Update failed
    }
});

Get Friend Information by User ID

You can use getFriendsInfo to retrieve friend information by user ID. This interface supports batch retrieval - you can pass multiple userId parameters to get information for multiple friends at once, with a maximum limit of 100 users.

Sample Code

// List of friend user IDs
List<String> userIds = new ArrayList<>();
userIds.add("user1");
userIds.add("user2");
userIds.add("user3");
RongCoreClient.getInstance().getFriendsInfo(userIds, new IRongCoreCallback.ResultCallback<List<FriendInfo>>() {
    @Override
    public void onSuccess(List<FriendInfo> friendInfos) {
        // Friend query successful
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // Friend query failed
    }
});

Search Friend Information by Nickname

You can use searchFriendsInfo to search for friend information by nickname.

The search first checks the friend remark name remark, then the friend name name. Results are returned when either field matches.

Sample Code

// Nickname keyword (required, max 64 characters)
String name = "name";
RongCoreClient.getInstance().searchFriendsInfo(name, new IRongCoreCallback.ResultCallback<List<FriendInfo>>() {
    @Override
    public void onSuccess(List<FriendInfo> friendInfos) {
        // Friend list query successful
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode e) {
        // Friend list query failed
    }
});

AppKey Permission	User Permission	Result
Free/NeedVerify/NoOneAllowed	Not set	Follows AppKey permission settings
Free/NeedVerify/NoOneAllowed	Set to (Free/NeedVerify/NoOneAllowed)	Follows user permission settings