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