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) {
      print(
          '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);

Blocklist

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) {
      print('onBlackListChanged');
    });

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);

Do-Not-Disturb

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) {
      print('onMuteListChanged');
});

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);