Managing friends

This document guides developers on how to use RC IM Web IMLib SDK to implement friend-related functions including adding friends, deleting friends, viewing friend lists, and managing friends.

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.

Friend Event Listening

The friend event listener receives notifications about friend-related events including: adding, deleting, application status changes, clearing all friends, and friend profile updates.

The returned data types are:

• Add friend: IFriendAdd
• Delete friend: IFriendDelete
• Clear all friends: number timestamp indicating when friends were cleared
• Friend request status: IFriendApplicationStatusChange
• Multi-device sync for friend info changes: IFriendInfoChangedSync

// Add friend event listener
RongIMLib.addEventListener(RongIMLib.Events.FRIEND_ADDED, (data) => {
  // data type: IFriendAdd
  console.info('Friend added event', data);
});
// Delete friend event listener
RongIMLib.addEventListener(RongIMLib.Events.FRIEND_DELETE, (data) => {
  // data type: IFriendDelete
  console.info('Friend deleted event', data);
});
// Clear all friends listener
RongIMLib.addEventListener(RongIMLib.Events.FRIEND_CLEARED, (data) => {
  // data type: number, timestamp when friends were cleared
  console.info('All friends cleared event', data);
});
// Friend request listener
RongIMLib.addEventListener(RongIMLib.Events.FRIEND_APPLICATION_STATUS_CHANGED, (data) => {
  // data type: IFriendApplicationStatusChange
  console.info('Friend request status changed', data);
});
// Multi-device sync for friend info changes
RongIMLib.addEventListener(RongIMLib.Events.FRIEND_INFO_CHANGED_SYNC, (data) => {
  // data type: IFriendInfoChangedSync
  console.info('[Multi-device sync] Friend info changed', data);
});

Friend Online Status and Profile Change Listening

For friend online status and profile changes, you don't need to actively subscribe via subscribeEvent. Simply set up the listener before establishing the SDK connection.

The callback uses SubscribeType to distinguish event types:

• SubscribeType.FRIEND_ONLINE_STATUS indicates friend online status changes
• SubscribeType.FRIEND_PROFILE_CHANGED indicates friend profile changes

// Friend online status and info sync completion
RongIMLib.addEventListener(RongIMLib.Events.SUBSCRIBED_USER_STATUS_CHANGE, (data) => {
  // Friend online status change
  if (data.subscribeType === RongIMLib.SubscribeType.FRIEND_ONLINE_STATUS) {
     console.info('Friend online status changed', data);
  } else if (data.subscribeType === RongIMLib.SubscribeType.FRIEND_USER_PROFILE) {
    // Friend profile change
     console.info('Friend profile changed', data);
  }
});

Friend Operations

Add Friend

Users can search for target users by username, user ID, or phone number, optionally include a request note, and submit friend requests via addFriend.

tip

A single user can add up to 3000 friends.

Friend Addition Permission Explanation

The default AppKey-level permission is Require user consent to add friends. Below shows the combined effect of AppKey and user level permissions:

AppKey Permission	User Permission	Result
Invisible to all, Visible to friends only, Visible to all	Not set	Follows AppKey permission
Invisible to all, Visible to friends only, Visible to all	Set (Invisible to all, Visible to all, Visible to friends only)	Follows user permission

Different Permission Flow Explanations

Scenario 1: Direct addition without verification

1. Both parties call setFriendListener to register friend event listeners.
2. User B sets friend addition permission to: Anyone can add directly (see FriendAddPermission)
3. User A calls addFriend, API returns processCode as 0, indicating direct friend addition. Both parties receive Events.FRIEND_ADDED event.

Scenario 2: Requires verification and consent

1. Both parties call setFriendListener to register friend event listeners.
2. User B sets friend addition permission to: Requires verification (see FriendAddPermission).
3. User A calls addFriend, API returns processCode as 25461, indicating pending verification. Both parties receive Events.FRIEND_APPLICATION_STATUS_CHANGED event.
4. User B receives the request via listener and can call:
   • acceptFriendApplication to accept, both parties receive Events.FRIEND_ADDED
   • refuseFriendApplication to reject, both parties receive Events.FRIEND_APPLICATION_STATUS_CHANGED with status REFUSED

API

RongIMLib.addFriend(userId, directionType, extra)

Parameters

Parameter	Type	Required	Description
userId	string	Yes	Target user ID to add as friend
directionType	DirectionType	Yes	Friend type
extra	string	No	Additional info for friend request, max 128 characters

Example Code

const userId = 'UserId';
const directionType = DirectionType.BOTH
const extra = 'Hello, I would like to add you as a friend.';

const res = await RongIMLib.addFriend(userId, directionType, extra);
console.info('Add friend request result:', res);

tip

The result contains code and processCode, where code indicates request status and processCode represents business status codes requiring follow-up.

Remove Friend

Call deleteFriends to batch remove friend relationships. Both parties receive Events.FRIEND_DELETE upon success.

API

RongIMLib.deleteFriends(userIds, directionType);

Parameters

Parameter	Type	Required	Description
userIds	string[]	Yes	Array of target user IDs to remove, max 100 users per operation
directionType	DirectionType	Yes	Friend type

Sample Code

const userIds = ['UserId1', 'UserId2'];
const directionType = DirectionType.BOTH;

const res = await RongIMLib.deleteFriends(userIds, directionType);
console.info('Friend removal result:', res);

Friend Information Settings

Call setFriendInfo to set a friend's remark name and extended information.

tip

• Extended information keys must be configured via the developer console or API before use (max 10 keys allowed), otherwise the operation will fail.
• When friend information is modified, other logged-in devices will receive the multi-device sync event Events.FRIEND_INFO_CHANGED_SYNC.

API

RongIMLib.setFriendInfo(userId, remark)

Parameters

Parameter	Type	Required	Description
userId	string	Yes	Friend user ID
remark	string	No	Friend remark name (max 64 characters). Leave empty to clear remark
extProfile	{[key: string]: string}	No	Extended information (max 10 custom attributes). Keys must be preconfigured via developer console or API

Sample Code

const userId = 'UserId';
const remark = 'Best Friend';

RongIMLib.setFriendInfo(userId, remark);

Check Friend Relationship

Call checkFriends to verify friend relationships (currently supports bidirectional checks only).

API

RongIMLib.checkFriends(userId, directionType);

Parameters

Parameter	Type	Required	Description
userIds	string[]	Yes	User ID list to check (max 20 users per operation)
directionType	DirectionType	Yes	Friend type to verify

Sample Code

const userIds = ['UserId1', 'UserId2'];
const directionType = DirectionType.BOTH;

const res = await RongIMLib.checkFriends(userIds, directionType);
console.info('Friend relationship check result:', res);

Set Friend Request Permission

Call setFriendAddPermission to configure friend request permissions. Uses App Key defaults if not set.

API

RongIMLib.setFriendAddPermission(permission)

Parameters

Parameter	Type	Required	Description
permission	FriendAddPermission	Yes	Friend request permission (see FriendAddPermission)

Sample Code

const permission = FriendAddPermission.Free; 

const res = await RongIMLib.setFriendAddPermission(permission);
console.info('Friend request permission setting result:', res);

Get Friend Request Permission

Call getFriendAddPermission to retrieve current user's friend request permissions.

API

RongIMLib.getFriendAddPermission();

Parameters

None

Sample Code

const res = await RongIMLib.getFriendAddPermission();
console.info('Friend request permission:', res);

Friend Requests

Accept Friend Request

After receiving a friend request, call acceptFriendApplication to establish the relationship. Both parties receive Events.FRIEND_ADDED upon success.

The request status changes to "Accepted" in the friend request list.

API

RongIMLib.acceptFriendApplication(userId)

Parameters

Parameter	Type	Required	Description
userId	string	Yes	Target user ID

Sample Code

const userId = 'UserId';

const res = await RongIMLib.acceptFriendApplication(userId);
console.info('Friend request acceptance result:', res);

Reject Friend Request

Call refuseFriendApplication to decline a request. Both parties receive Events.FRIEND_APPLICATION_STATUS_CHANGED with "Rejected" status.

API

RongIMLib.refuseFriendApplication(userId, reason);

Parameters

Parameter	Type	Required	Description
userId	string	Yes	Target user ID
reason	string	No	Rejection reason (max 128 characters)

Sample Code

const userId = 'UserId';

const res = await RongIMLib.refuseFriendApplication(userId, reason);
console.info('Friend request rejection result:', res);

Paginated Friend Request List

Call getFriendApplications to view all friend requests received by the user and all friend requests sent by the user.

tip

• Friend requests expire after 7 days. RC servers store request data for up to 7 days. Requests older than 7 days require resubmission.
• This API doesn't return the total request count.
• Electron supports conditional queries by request type (types) and status (status), while Web doesn't currently support this feature.

Interface

 RongIMLib.getFriendApplications(option, types, status)

Parameters

Parameter	Type	Required	Description
option	IPagingQueryOption	No	Pagination parameters. Default: 50 records. Maximum: 100 records.
types	FriendApplicationType	No	Electron only. Request types: 1: Sent requests, 2: Received requests.
status	FriendApplicationStatus	No	Electron only. Request status

Sample Code

// Invalid for Web
const types = [FriendApplicationType.SENT, FriendApplicationType.RECEIVED];
// Invalid for Web
const status = [FriendApplicationStatus.ACCEPTED];

const option = {
  count: 50,
  pageToken: '',
  order: false,
};

const res = await RongIMLib.getFriendApplications(option, types, status);
console.info('Friend request list:', res);

Get Friend List

Get Friend List

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

Interface

RongIMLib.getFriends(directionType, option)

Parameters

tip

For Web platform: When pageToken isn't provided, the first page is queried by default. For paginated queries, use the pageToken returned in the API response for subsequent queries.

Parameter	Type	Required	Description
directionType	QueryFriendsDirectionType	Yes	Friend type
option	IPagingQueryOption	No	Web only. Pagination parameters. Default: 50 records. Maximum: 100 records. Electron retrieves full lists—implement pagination logic at the application layer if needed.

Sample Code

const directionType = QueryFriendsDirectionType.BOTH; 
const option = {
  count: 50,
  pageToken: '',
  order: false,
};

const friendsList = await RongIMLib.getFriends(directionType, option);
console.info('Friend list:', friendsList);

Get Friend Info by User ID

Call getFriendsInfo to retrieve friend information.

Interface

RongIMLib.getFriendsInfo(userIds)

Parameters

Parameter	Type	Required	Description
userIds	string[]	Yes	User ID list. Maximum: 100 friend records per request.

Sample Code

const userIds = ['user1', 'user2', 'user3'];

const friendsInfo = await RongIMLib.getFriendsInfo(userIds);
console.info('Friend info list:', friendsInfo);

Search Friend Info by Nickname

Call searchFriendsInfo to search for friends.

warning

• Electron only.
• Searches first match against friend remarks (remark), then friend names (name). Returns results when either field matches.

Interface

RongIMLib.searchFriendsInfo(name)

Parameters

Parameter	Type	Required	Description
name	string	Yes	Nickname keyword (max 64 characters). Supports fuzzy search. Empty searches or pure whitespace aren't supported.

Sample Code

const name = 'userName';

const searchResults = await RongIMLib.searchFriendsInfo(name);
console.info('Friend search results:', searchResults);