Instant Messaging
Android
Getting Started
Introduction
Overview
Features
Limits
Features
Account Integration and Login
Group Chat
Chat Room
Chat Room Tags
Multi-device Login
Statistics Monitoring
Integration
Interface Overview
Integrate and Initialize SDK
Login
Message Sending
Message Receiving
Recent Chats
Server Sessions
User Profile
User Relationship
Online Status Subscription
System Notification
Push and Message Alert
Team
Superteam
Chat Room
Moderation
Chat Extension
Miscellaneous Features
Best Practice
Traffic Control in Chat Rooms
API Reference
Android API Reference
Android Status Codes

User Relationship

Update time: 2021/12/03 17:20:03

CommsEase provides three built-in user relations, such as friend list, blocklist, and Do Not Disturb list. The three relations are independent. The three relations can exist between two users.

Friend list

Getting the friend list

Getting accounts of all friends

The API is synchronous and returns the accounts of all friends.

  • API prototype
/**
 * Get accounts of all friends.
 *
 * @return - friend accounts.
 */
List<String> getFriendAccounts();
  • Example
List<String> friends = NIMClient.getService(FriendService.class).getFriendAccounts();

Getting the profiles of all friends

  • API prototype
/**
 * Get the profiles of all friends.
 *
 * @return - Friends set.
 */
java.util.List<Friend> getFriends();

Getting the friend list by account

  • API prototype
/**
 * Get the friend list by user account.
 *
 * @param account - User account.
 * @return - Corresponding friends of the account.
 */
Friend getFriendByAccount(String account);
  • Example
Friend friend = NIMClient.getService(FriendService.class).getFriendByAccount("account");

Get accounts by alias

Get the list of friend accounts with specified alias from the local database.

  • API prototype
/**
 * Query accounts by alias.
 *
 * @param alias - Alias.
 * @return - List of accounts.
 */
InvocationFuture<List<String>> searchAccountByAlias(String alias);
  • Example
NIMClient.getService(FriendService.class).searchAccountByAlias("alias").setCallback(new RequestCallbackWrapper<List<String>>() {
    @Override
    public void onResult(int code, List<String> result, Throwable exception) {
        if (code == ResponseCode.RES_SUCCESS) {
            // Success.
        } else {
            // Failure. See the code for error code
        }

        if (exception != null) {
            // Error
        }
    }
});

Getting friends by keyword

/**
 * Search all friends by keyword.
 *
 * @param keyword - Keyword.
 * @return - friend list.
 */
InvocationFuture<java.util.List<Friend>> searchFriendsByKeyword(java.lang.String keyword);

Managing the friend list

Requesting for friendship

Two verification types for adding friends (see VerifyType): add as friend or send a friend request. By the latter, friendship can be created with the permission of the peer.

When adding friends, you must create AddFriendData and join the account of the peer, friend verification type, and additional information (optional).

VerifyType attribute:

VerifyType attribute Description
DIRECT_ADD Add as friend.
VERIFY_REQUEST Send a friend request.

AddFriendData interface:

Return AddFriendData interface Description
String getAccount() Get an account.
String getMsg() Get additional information for friend requests.
VerifyType getVerifyType() Get the type of friend requests.
  • API prototype
/**
 * Friend requests.
 *
 * @param data - Friend request information (including account of the peer, verification type of friend request, P.S.)
 * @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error codes will be returned.
 */
InvocationFuture<Void> addFriend(AddFriendData data);
  • Parameters
Parameter Description
data Friend request information (including account of the peer, verification type of friend request, and remark)
  • Example
final VerifyType verifyType = VerifyType.VERIFY_REQUEST; // Initiate the request for friend verification
String msg = "P.S. for friend request";
NIMClient.getService(FriendService.class).addFriend(new AddFriendData(account, verifyType, msg))
	.setCallback(new RequestCallback<Void>() {... });

Response to friend requests

Accepts or rejects the received friend request.

  • API prototype
/**
 * Accept or reject a friend request.
 *
 * @param account - Account of the peer.
 * @param agree - "true" indicates to accept request; "false" indicates to reject request.
 * @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
 */
InvocationFuture<Void> ackAddFriendRequest(String account, boolean agree);
  • Parameters
Parameter Description
account Account of the peer.
agree "true" indicates approve; "false" indicates reject.
  • Example
// Take "Accept friend request of the peer" for an example
NIMClient.getService(FriendService.class).ackAddFriendRequest(account, true).setCallback(...);

After friends related operations are implemented, the peer will receive a system notification SystemMessage. See System Notification.

  • The field value of friends related system notification "SystemMessage - getType()" is "SystemMessageType.AddFriend".
  • "getEvent()" of "AddFriendNotify" type object that is acquired through "SystemMessage - getAttachObject()" is used to get detailed operation event.

AddFriendNotify.Event attribute

AddFriendNotify.Event attribute Description
RECV_ADD_FRIEND_DIRECT The peer adds you as friend.
RECV_ADD_FRIEND_VERIFY_REQUEST Send friend request by the peer.
RECV_AGREE_ADD_FRIEND Approve friend request by the peer.
RECV_REJECT_ADD_FRIEND Reject friend request by the peer.
  • Example
NIMClient.getService(SystemMessageObserver.class).observeReceiveSystemMsg(systemMessageObserver, register);

Observer<SystemMessage> systemMessageObserver = new Observer<SystemMessage>() {
    @Override
    public void onEvent(SystemMessage systemMessage) {
        if (systemMessage.getType() == SystemMessageType.AddFriend) {
            AddFriendNotify attachData = (AddFriendNotify) message.getAttachObject();
            if (attachData != null) {
            // Handle different events.
                if (attachData.getEvent() == AddFriendNotify.Event.RECV_ADD_FRIEND_DIRECT) {
                // The peer  adds you as friend.
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_AGREE_ADD_FRIEND) {
                // The peer accepts your request for friend verification.
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_REJECT_ADD_FRIEND) {
                // The peer rejects your request for friend verification.
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_ADD_FRIEND_VERIFY_REQUEST) {
                // The peer requests for adding you as friends. In general scene, users may accept or reject friend request of the peer.
                // Get additional information for friend verification request using message.getContent().
                }
            }
        }
    }
};

Listening for friendship changes

Friendship changes may trigger a callback:

  • API prototype
/**
 * Listen for notification for friends changes.
 *
 * @param observer - Observer. The parameter is received notification for friends change.
 * @param register - "true" indicates to register Listen foring, "false" is to cancel Listen foring.
 */
void observeFriendChangedNotify(Observer<FriendChangedNotify> observer, boolean register);
  • Parameters

FriendChangedNotify interface

Return Method Description
List getAddedOrUpdatedFriends() Return added or updated friends.
List getDeletedFriends() Return deleted friends.

Friend interface

Return Method Description
String getAccount() Get friend account.
String getAlias() Get friend alias.
Map getExtension() Get the extension field.
String getServerExtension() Get the extension field of server. Only server interface can be changed.
  • Example
NIMClient.getService(FriendServiceObserve.class).observeFriendChangedNotify(friendChangedNotifyObserver, true);
private Observer<FriendChangedNotify> friendChangedNotifyObserver = new Observer<FriendChangedNotify>() {
    @Override
    public void onEvent(FriendChangedNotify friendChangedNotify) {
        List<Friend> addedOrUpdatedFriends = friendChangedNotify.getAddedOrUpdatedFriends(); // New added friends
        List<String> deletedFriendAccounts = friendChangedNotify.getDeletedFriends(); // Deleted or removed friends
       ...
    }
};

Delete a friend

The relationship will be relieved automatically after deleting friends. Both parties will be disappeared from the list of friends. By default, both parties can still chat with each other after deleting friends.

  • API prototype
/**
 * Delete friends.
 *
 * @param account - account whose friends are removed.
 * @param deleteAlias - It determines to clear alias.
 * @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
 */
InvocationFuture<java.lang.Void> deleteFriend(java.lang.String account,boolean deleteAlias);
  • Example
NIMClient.getService(FriendService.class).deleteFriend(account,true)
	.setCallback(new RequestCallback<Void>() {... });

Checking friendship

  • API prototype
/**
 * The API determines whether a user is in the friend list.
 *
 * @param account - Account of the peer.
 * It determines that the account is in the friend list.
 */
boolean isMyFriend(String account);
  • Example
boolean isMyFriend = NIMClient.getService(FriendService.class).isMyFriend(account);

Modifying friend remarks

Updates friend's alias and friend extension field. See FriendFieldEnum.

FriendFieldEnum schema:

Field Description
ALIAS The alias of the user account.
EXTENSION Extension field.
undefined Undefined domain.
  • API prototype
/**
 * Update friends.
 *
 * @param friendAccount - Friend account to be updated.
 * @param fields - Set of all fields to be updated. It is available to update alias and extension field now.
 * Notes: The maximum length of alias is 128 characters. Extension field must be input to Map; key is String; Value is Object; SDK is responsible for converting it into Json String; the maximum length is 256 characters.
 * @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
 */
InvocationFuture<Void> updateFriendFields(String friendAccount, Map<FriendFieldEnum, Object> fields);
  • Parameters
Parameter Description
friendAccount Friend account to be updated.
fields Set of all fields to be updated. You can update alias and extension field now.
Notes: The maximum length of alias is 128 characters. Extension field must be input to Map; key is String; Value is Object; The SDK converts it into JSON String; the maximum length is 256 characters.
  • Example
// Update the alias.
Map<FriendFieldEnum, Object> map = new HashMap<>();
map.put(FriendFieldEnum.ALIAS, content);
NIMClient.getService(FriendService.class).updateFriendFields(data, map).setCallback(callback);

// Update the extension field.
Map<FriendFieldEnum, Object> map = new HashMap<>();
Map<String, Object> exts = new HashMap<>();
exts.put("ext", "ext");
map.put(FriendFieldEnum.EXTENSION, exts);
NIMClient.getService(FriendService.class).updateFriendFields(data, map).setCallback(callback);

Blocklist

When a user is added to the blocklist, you will not receive any message or request from the user. For example, if user A adds user B to the blocklist, user A will not receive any message from user B. But user B can read any message sent from user A.

Getting the blocklist

  • API prototype
/**
 * Return the users in Blocklist.
 *
 * @return - all accounts in the blocklist.
 */
List<String> getBlocklist();
  • Example
List<String> accounts = NIMClient.getService(FriendService.class).getBlocklist();

Adding a user to a blocklist

  • API prototype
/**
 * Add a user to a blocklist.
 *
 * @param account - User account.
 * @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
 */
InvocationFuture<Void> addToBlocklist(String account);
  • Example
NIMClient.getService(FriendService.class).addToBlocklist(account)
   .setCallback(new RequestCallback<Void>() {... });

Remove a user from a blocklist

  • API prototype
/**
 * Remove a user from the blocklist.
 *
 * @param account - User account.
 * @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
 */
InvocationFuture<Void> removeFromBlocklist(String account);
  • Example
NIMClient.getService(FriendService.class).removeFromBlocklist(user.getAccount())
	.setCallback(new RequestCallback<Void>() {... });

Listening for blocklist changes

  • API prototype
/**
 * Listen for notification for blocklist change.
 *
 * @param observer - Observer. The parameter is received notification for blocklist change.
 * @param register - "true" indicates to register Listen foring, "false" is to cancel Listen foring.
 */
void observeBlocklistChangedNotify(Observer<BlocklistChangedNotify> observer, boolean register);
  • Parameters

BlocklistChangedNotify interface:

Return Method Description
List getAddedAccounts() Return user accounts added to the blocklist.
List getRemovedAccounts() Return user accounts removed from the blocklist.
  • Example
NIMClient.getService(FriendServiceObserve.class)
   .observeBlocklistChangedNotify(BlocklistChangedNotifyObserver, true);

private Observer<BlocklistChangedNotify> BlocklistChangedNotifyObserver
    = new Observer<BlocklistChangedNotify>() {
    @Override
    public void onEvent(BlocklistChangedNotify BlocklistChangedNotify) {
        List<String> addedAccounts = BlocklistChangedNotify.getAddedAccounts(); // Set of accounts added to the blocklist
        List<String> removedAccounts = BlocklistChangedNotify.getRemovedAccounts(); // Set of accounts removed from Blocklist
       ...
    }
};

Determining whether a user is in the blocklist

  • API prototype
/**
 * The API determines whether a user is added to the blocklist.
 *
 * @param account - User account.
 * @return - The API determines that a user is added to the blocklist.
 */
boolean isInBlocklist(String account);
  • Example
boolean black = NIMClient.getService(FriendService.class).isInBlocklist(account);

Do Not Disturb setting

Sets mute for users. When the message from a user is received, you will not be reminded by notification bar, vibration and bell in the range of YunXin. Message reminding setting for individual user supports multi-client synchronization.

Get the Do Not Disturb list

  • API prototype
/**
 * Get the list of all accounts without message alert (list of accounts  that apply Do Not Disturb).
 *
 * @return - Accounts without message alert.
 */
List<String> getMuteList();
  • Example
List<String> accounts = NIMClient.getService(FriendService.class).getMuteList();

Do Not Disturb setting

  • API prototype
/**
 * Configure the Do Not Disturb setting.
 *
 * @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
 */
InvocationFuture<Void> setMessageNotify(String account, boolean notify);
  • Parameters
Parameter Description
account Account to be set with notification.
notify Whether to notify the message from a user. false represents no notification.
  • Example
NIMClient.getService(FriendService.class).setMessageNotify(account, checkState)
	.setCallback(new RequestCallback<Void>() {
		@Override
		public void onSuccess(Void param) {
			if (checkState) {
				Toast.makeText(UserProfileActivity.this, "Enable message alert", Toast.LENGTH_SHORT).show();
			} else {
				Toast.makeText(UserProfileActivity.this, "Disable message alert", Toast.LENGTH_SHORT).show();
			}
});

Listening for change in the Do Not Disturb list

  • API prototype
/**
 * Listen for the notification for change in the Do Not Disturb list.
 *
 * @param observer - Observer. The parameter is received notification for change in mute list.
 * @param register - "true" indicates to register Listen foring, "false" is to cancel Listen foring.
 */
void observeMuteListChangedNotify(Observer<MuteListChangedNotify> observer, boolean register);
  • Parameters

MuteListChangedNotify interface

Return Method Description
String getAccount() User with change in mute setting.
boolean isMute() Set that the user is muted.
  • Example
NIMClient.getService(FriendServiceObserve.class).observeMuteListChangedNotify(
    new Observer<MuteListChangedNotify>() {
        @Override
        public void onEvent(MuteListChangedNotify notify) {
            // notify.isMute() - It determines to be muted.
        }
    }, register);

Checking the Do Not Disturb status

  • API prototype
/**
 * The API determines that a user requires message alert/mute.
 *
 * @param account - User account.
 * @return - true: to set tip, false: to set mute.
 */
boolean isNeedMessageNotify(String account);
  • Example
boolean notice = NIMClient.getService(FriendService.class).isNeedMessageNotify(account);
Was this topic helpful?
Yes
No
  • Friend list
  • Getting the friend list
  • Getting accounts of all friends
  • Getting the profiles of all friends
  • Getting the friend list by account
  • Get accounts by alias
  • Getting friends by keyword
  • Managing the friend list
  • Requesting for friendship
  • Response to friend requests
  • Listening for friendship related operations
  • Listening for friendship changes
  • Delete a friend
  • Checking friendship
  • Modifying friend remarks
  • Blocklist
  • Getting the blocklist
  • Adding a user to a blocklist
  • Remove a user from a blocklist
  • Listening for blocklist changes
  • Determining whether a user is in the blocklist
  • Do Not Disturb setting
  • Get the Do Not Disturb list
  • Do Not Disturb setting
  • Listening for change in the Do Not Disturb list
  • Checking the Do Not Disturb status