User relation

Update time: 2023/02/01 16:55:22

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
/// Get the accounts of all friends.
/// List of friends
Future<NIMResult<List<NIMFriend>>> getFriendList();
  • Example
NIMResult<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
/// 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
NIMResult<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
/// 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
// 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

NimCore.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
NimCore.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
/// Delete a friend
Future<NIMResult<void>> deleteFriend({required String userId, bool includeAlias = true});
  • Example
NIMResult<void> addFriendResult = await NimCore.instance.userService.deleteFriend(userId: account, includeAlias: true);

Check for friend relationship

  • API prototype
/// Whether an account is a friend.
Future<NIMResult<bool>> isMyFriend(String userId);
  • Example
NIMResult<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
/// 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
// 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
/// Return users in a blocklist.
Future<NIMResult<List<String>>> getBlackList();
  • Example
NIMResult<List<String>> userInfoResult2 = await NimCore.instance.userService.getBlackList();

Add a user to the blocklist

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

Remove a user from the blocklist

  • API prototype
/// Remove a user from the blocklist
Future<NIMResult<void>> removeFromBlackList(String userId);
  • Example
NIMResult<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
NimCore.instance.userService.onBlackListChanged.listen((event) {

Check whether an account is included in the blocklist

  • API prototype
/// Evaluate whether a user is added to the blacklist.
Future<NIMResult<bool>> isInBlackList(String userId);
  • Example
NIMResult<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
/// Get the list of accounts for which messages are not alerted.
Future<NIMResult<List<String>>> getMuteList();
  • Example
NIMResult<List<String>> result = await NimCore.instance.userService.getMuteList();

Set the mute status

  • API prototype
/// 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
NIMResult<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
NimCore.instance.userService.onMuteListChanged.listen((event) {

Check accounts for Do-Not-Disturb

  • API prototype
/// Evaluate whether an account required notification alerts or Do-Not-Disturb
Future<NIMResult<bool>> isMute(String userId);
  • Example
NIMResult<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