User relation

Update time: 2024/03/07 11:13:59

User relationship data

Instant Messaging provides three built-in user relationships: friends, blocklist, and Do-Not-Disturb. The three relationships are independent of each other and do not affect each other. These relationships can exist between any two users at the same time.

Friend relationship

Get friend relationship

Get the accounts of all friends

  • API prototype
dart/// Get the accounts of all friends.
/// List of friends
Future<NIMResult<List<NIMFriend>>> getFriendList();
  • Example
dartNIMResult<List<NIMFriend>> result = await NimCore.instance.userService.getFriendList();

Manage friends

Send friend requests

You can configure two verification types for adding friends (see NIMVerifyType): adding a friend without verification and sending a friend request with verification. The latter requires the consent of the invitee to establish a friendship relationship.

NIMVerifyType representation

Field Description
directAdd Add friends without verification.
verifyRequest Add friends with verification.
  • API prototype
dart/// Send a friend request
Future<NIMResult<void>> addFriend({required String userId, String? message, required NIMVerifyType verifyType});
  • Parameters
Parameter Description
userId The account you want to add to your friend list.
message Additional message in a friend request.
verifyType Verification type.
  • Example
dartNIMResult<void> addFriendResult = await NimCore.instance.userService.addFriend(userId: account, verifyType: NIMVerifyType.directAdd);

Respond to friend requests

After receiving a friend request, you can accept or reject the request

  • API prototype
dart/// Accept or reject a friend request
Future<NIMResult<void>> ackAddFriend({required String userId, bool isAgree = true});
  • Parameters
Parameter Description
userId The account you want to add to your friend list.
isAgree true: acceot the friend request, false: reject the friend request.
idServer The ID of the system notification for receiving a friend request (required for web apps).
  • Example
dart// Accept a friend request
NimCore.instance.userService.ackAddFriend(userId: account, isAgree: true);


Listen to friend operations

After a friend operation is performed, the friend account will receive a system notification. For more information, see System notifications.

  • The NimCore.instance.systemMessageService.onReceiveSystemMsg event.type field of system notifications for friend operations and events is set to SystemMessageType.addFriend.

  • Get the operation event using the getEvent() method of the AddFriendNotify object of NimCore.instance.systemMessageService.onReceiveSystemMsg attachObject.

  • Example

dartNimCore.instance.systemMessageService.onReceiveSystemMsg.listen((event) {
          'onReceiveSystemMsg ${event.type} ${event.fromAccount}');
      if (event.type == SystemMessageType.addFriend) {

Listen to changes of friend relations

If the friend relationship changes, a callback will be triggered:

  • Observers
Observer Description
NimCore.instance.userService.onFriendAddedOrUpdated The event of adding or updating a new friend.
NimCore.instance.userService.onFriendDeleted The event of deleting a friend.

NIMFriend interface

Parameter Type Description
userId String? The ID of a friend account.
alias String? The alias of a friend.
serverExt String? The extension field for the server operations.
  • Example
dartNimCore.instance.userService.onFriendAddedOrUpdated.listen((event) {
      print('onFriendAddedOrUpdated ${event.toString()}');
NimCore.instance.userService.onFriendDeleted.listen((event) {
      print('onFriendDeleted ${event.toString()}');

Delete a friend

After deleting a friend, the friendship between the two users will be automatically terminated. After deleting a friend, you can still chat with the user by default.

  • API prototype
dart/// Delete a friend
Future<NIMResult<void>> deleteFriend({required String userId, bool includeAlias = true});
  • Example
dartNIMResult<void> addFriendResult = await NimCore.instance.userService.deleteFriend(userId: account, includeAlias: true);

Check for friend relationship

  • API prototype
dart/// Whether an account is a friend.
Future<NIMResult<bool>> isMyFriend(String userId);
  • Example
dartNIMResult<bool> isMyFriendResult = await NimCore.instance.userService.isMyFriend(account);

Edit the nickname of a friend

You can update friend's nickname and the extension field.

  • API prototype
dart/// Update a friend
Future<NIMResult<void>> updateFriend({required String userId, required String alias});
  • Parameters
Parameter Description
userId The friend account to be updated.
alias The alias of a friend.
The alias can contain up to 128 characters
  • Example
dart// Update the nickname of a friend
NIMResult<void> updateMyUserInfoResult = await NimCore.instance.userService.updateFriend(userId: account, alias: testFriendAlias);


After adding users to the blocklist, they will no longer receive any messages or requests from you. For example: user A adds user B to the blocklist, and user A will not receive the messages sent by user B. The messages sent by user A can still be viewed by user B.

Get the blocklist

  • API prototype
dart/// Return users in a blocklist.
Future<NIMResult<List<String>>> getBlackList();
  • Example
dartNIMResult<List<String>> userInfoResult2 = await NimCore.instance.userService.getBlackList();

Add a user to the blocklist

  • API prototype
dart/// Add a user to the blocklist
InvocationFuture<Void> addToBlackList(String userId);
  • Example
dartFuture<NIMResult<void>> addToBlackList(String userId);

Remove a user from the blocklist

  • API prototype
dart/// Remove a user from the blocklist
Future<NIMResult<void>> removeFromBlackList(String userId);
  • Example
dartNIMResult<void> addToBlackListResult = await NimCore.instance.userService.removeFromBlackList(account);

Listen to changes of the blocklist

  • Observers
Observer Description
NimCore.instance.userService.onBlackListChanged The event of blocklist changes.
  • Example
dartNimCore.instance.userService.onBlackListChanged.listen((event) {

Check whether an account is included in the blocklist

  • API prototype
java/// Evaluate whether a user is added to the blacklist.
Future<NIMResult<bool>> isInBlackList(String userId);
  • Example
dartNIMResult<bool> isInBlackListResult = await NimCore.instance.userService.isInBlackList(account);


You can set Do Not Disturb status a specified users. When receiving a message from the user, CommsEase will no longer sent alerts on the notification bar, or using vibration and ringing. The notification alert supports multiple device synchronization.

Get the Do-Not-Disturb list

  • API prototype
dart/// Get the list of accounts for which messages are not alerted.
Future<NIMResult<List<String>>> getMuteList();
  • Example
dartNIMResult<List<String>> result = await NimCore.instance.userService.getMuteList();

Set the mute status

  • API prototype
dart/// Mute users
Future<NIMResult<void>> setMute({required String userId, required isMute});
  • Parameters
Parameter Description
userId Account to be applied with Do-Not-Disturb
isMute Whether messages sent from the account are alerted. If false, messages are not alerted.
  • Example
dartNIMResult<void> addToBlackListResult = await NimCore.instance.userService.setMute(userId: account, isMute: true);

Listen to changes of the Do-Not-Disturb list

  • Observers
Observer Description
NimCore.instance.userService.onMuteListChanged The do-not-disturb state changes
  • Example
dartNimCore.instance.userService.onMuteListChanged.listen((event) {

Check accounts for Do-Not-Disturb

  • API prototype
dart/// Evaluate whether an account required notification alerts or Do-Not-Disturb
Future<NIMResult<bool>> isMute(String userId);
  • Example
dartNIMResult<bool> result = await NimCore.instance.userService.isMute(account);
Was this page helpful?
  • Friend relationship
  • Get friend relationship
  • Get the accounts of all friends
  • Manage friends
  • Send friend requests
  • Respond to friend requests
  • Listen to friend operations
  • Listen to changes of friend relations
  • Delete a friend
  • Check for friend relationship
  • Edit the nickname of a friend
  • Blocklist
  • Get the blocklist
  • Add a user to the blocklist
  • Remove a user from the blocklist
  • Listen to changes of the blocklist
  • Check whether an account is included in the blocklist
  • Do-Not-Disturb
  • Get the Do-Not-Disturb list
  • Set the mute status
  • Listen to changes of the Do-Not-Disturb list
  • Check accounts for Do-Not-Disturb