云信目前提供好友关系、黑名单与免打扰三种内置用户关系。三种关系互相独立，互不影响。即任意两个用户之间可以同时存在这三种关系。

好友关系

获取好友关系

获取所有好友账号

该方法是同步方法，返回我的好友帐号集合。

• API 原型

java/**
 * 获取所有的好友帐号
 *
 * @return 好友帐号集合
 */
List<String> getFriendAccounts();

• 示例

javaList<String> friends = NIMClient.getService(FriendService.class).getFriendAccounts();

获取所有好友信息

• API 原型

java/**
 * 获取所有的好友关系
 *
 * @return 好友集合
 */
java.util.List<Friend> getFriends();

根据账号获取

• API 原型

java/**
 * 根据用户账号获取好友关系
 *
 * @param account 用户账号
 * @return 该账号对应的好友关系
 */
Friend getFriendByAccount(String account);

• 示例

javaFriend friend = NIMClient.getService(FriendService.class).getFriendByAccount("account");

根据备注名获取

从本地数据库获取具有指定备注名的好友账号列表

• API原型

java/**
 * 根据备注反查账号
 *
 * @param alias 备注
 * @return 账号列表
 */
InvocationFuture<List<String>> searchAccountByAlias(String alias);

• 示例

javaNIMClient.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) {
            // 成功
        } else {
            // 失败，错误码见code
        }

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

根据备注名关键字获取

java/**
 * 搜索与备注名的关键字匹配的所有好友
 *
 * @param keyword 关键字
 * @return 好友集合
 */
InvocationFuture<java.util.List<Friend>> searchFriendsByKeyword(java.lang.String keyword);

处理好友关系

申请添加好友

目前添加好友有两种验证类型（见 VerifyType）：直接添加为好友和发起好友验证请求。后者需要对方同意才能建立好友关系。

添加好友时需要构造 AddFriendData，需要填入包括对方帐号，好友验证类型及附言（可选）。

VerifyType 属性说明：

VerifyType 属性	说明
DIRECT_ADD	直接加对方为好友
VERIFY_REQUEST	发起好友验证请求

AddFriendData 接口说明：

返回值	AddFriendData 接口	说明
String	getAccount()	获取帐号
String	getMsg()	获取好友请求附言
VerifyType	getVerifyType()	获取好友请求方式

• API 原型

java/**
 * 好友请求
 *
 * @param data 好友请求信息（包括对方帐号、好友请求验证类型、附言）
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> addFriend(AddFriendData data);

• 参数说明

参数	说明
data	好友请求信息（包括对方帐号、好友请求验证类型、附言）

• 示例

javafinal VerifyType verifyType = VerifyType.VERIFY_REQUEST; // 发起好友验证请求
String msg = "好友请求附言";
NIMClient.getService(FriendService.class).addFriend(new AddFriendData(account, verifyType, msg))
	.setCallback(new RequestCallback<Void>() { ... });

回应好友申请

收到好友申请后，可以通过或者拒绝该请求。

• API 原型

java/**
 * 同意/拒绝好友请求
 *
 * @param account 对方帐号
 * @param agree   true表示同意，false表示拒绝
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> ackAddFriendRequest(String account, boolean agree);

• 参数说明

参数	说明
account	对方帐号
agree	true 表示同意，false 表示拒绝

• 示例

java// 以通过对方好友请求为例
NIMClient.getService(FriendService.class).ackAddFriendRequest(account, true).setCallback(...);

监听好友相关操作

好友关系相关操作执行后，对方会收到一条系统通知 SystemMessage。具体可参见系统通知。

• 好友相关的系统通知 SystemMessage - getType() 字段值统一为 SystemMessageType.AddFriend。
• 通过 SystemMessage - getAttachObject() 获取到的 AddFriendNotify类型对象 的 getEvent() 来获取具体的操作事件。

AddFriendNotify.Event 属性说明：

AddFriendNotify.Event 属性	说明
RECV_ADD_FRIEND_DIRECT	对方直接加你为好友
RECV_ADD_FRIEND_VERIFY_REQUEST	对方发起好友验证请求
RECV_AGREE_ADD_FRIEND	对方同意加你为好友
RECV_REJECT_ADD_FRIEND	对方拒绝加你为好友

• 示例

javaNIMClient.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) {
            // 针对不同的事件做处理
                if (attachData.getEvent() == AddFriendNotify.Event.RECV_ADD_FRIEND_DIRECT) {
                // 对方直接添加你为好友
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_AGREE_ADD_FRIEND) {
                // 对方通过了你的好友验证请求
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_REJECT_ADD_FRIEND) {
                // 对方拒绝了你的好友验证请求
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_ADD_FRIEND_VERIFY_REQUEST) {
                // 对方请求添加好友，一般场景会让用户选择同意或拒绝对方的好友请求。
                // 通过message.getContent()获取好友验证请求的附言
                }
            }
        }
    }
};

监听好友关系变更

好友关系出现变更后，会触发回调：

• API 原型

java/**
 * 监听好友关系变化通知
 *
 * @param observer 观察者，参数为收到的好友关系变化通知。
 * @param register true为注册监听，false为取消监听
 */
void observeFriendChangedNotify(Observer<FriendChangedNotify> observer, boolean register);

• 参数说明

FriendChangedNotify 接口说明：

返回值	FriendChangedNotify 接口	说明
List	getAddedOrUpdatedFriends()	返回增加或者发生变更的好友关系
List	getDeletedFriends()	返回被删除的的好友关系

Friend 接口说明：

返回值	Friend 接口	说明
String	getAccount()	获取好友帐号
String	getAlias()	获取好友备注名
Map	getExtension()	获取扩展字段
String	getServerExtension()	获取服务器扩展字段，仅服务器接口可修改

• 示例

javaNIMClient.getService(FriendServiceObserve.class).observeFriendChangedNotify(friendChangedNotifyObserver, true);
private Observer<FriendChangedNotify> friendChangedNotifyObserver = new Observer<FriendChangedNotify>() {
    @Override
    public void onEvent(FriendChangedNotify friendChangedNotify) {
        List<Friend> addedOrUpdatedFriends = friendChangedNotify.getAddedOrUpdatedFriends(); // 新增的好友
        List<String> deletedFriendAccounts = friendChangedNotify.getDeletedFriends(); // 删除好友或者被解除好友
        ...
    }
};

删除好友

删除好友后，将自动解除双方的好友关系，双方的好友列表中均不存在对方。删除好友后，默认情况下双方依然可以聊天。

• API 原型

java/**
 * 删除好友
 *
 * @param account 要解除好友关系的帐号
 * @param deleteAlias 是否同时清除备注名
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<java.lang.Void> deleteFriend(java.lang.String account,boolean deleteAlias);

• 示例

javaNIMClient.getService(FriendService.class).deleteFriend(account,true)
	.setCallback(new RequestCallback<Void>() { ... });

检测是否为好友

• API 原型

java/**
 * 是否为我的好友
 *
 * @param account 对方帐号
 * @return 该帐号是否为我的好友
 */
boolean isMyFriend(String account);

• 示例

javaboolean isMyFriend = NIMClient.getService(FriendService.class).isMyFriend(account);

修改好友备注

目前支持更新好友的备注名和好友关系扩展字段，见 FriendFieldEnum。

FriendFieldEnum 属性说明:

FriendFieldEnum 属性	说明
ALIAS	备注名
EXTENSION	扩展字段
undefined	未定义的域

• API 原型

java/**
 * 更新好友关系
 *
 * @param friendAccount 待更新的好友账号
 * @param fields        待更新的所有字段集合，目前支持更新备注名和扩展字段
 *                      注意:备注名最长128个字符，扩展字段需要传入Map，key为String，Value为Object，SDK负责转成Json String，最大长度256字符。
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> updateFriendFields(String friendAccount, Map<FriendFieldEnum, Object> fields);

• 参数说明

参数	说明
friendAccount	待更新的好友账号
fields	待更新的所有字段集合，目前支持更新备注名和扩展字段。 注意:备注名最长 128 个字符，扩展字段需要传入 Map，key 为 String，Value 为 Object，SDK 负责转成Json String，最大长度 256 字符。

• 示例

java// 更新备注名
Map<FriendFieldEnum, Object> map = new HashMap<>();
map.put(FriendFieldEnum.ALIAS, content);
NIMClient.getService(FriendService.class).updateFriendFields(data, map).setCallback(callback);

// 更新扩展字段
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);

黑名单

将用户加入黑名单后，将不在收到对方发来的任何消息或者请求。例如：A用户将B用户加入黑名单，B用户发送的消息，A用户将收不到。A用户发送的消息，B用户依然可以看到。

获取黑名单列表

• API 原型

java/**
 * 返回黑名单中的用户列表
 *
 * @return 所有黑名单帐号集合
 */
List<String> getBlackList();

• 示例

javaList<String> accounts = NIMClient.getService(FriendService.class).getBlackList();

添加用户到黑名单

• API 原型

java/**
 * 添加用户到黑名单
 *
 * @param account 用户帐号
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> addToBlackList(String account);

• 示例

javaNIMClient.getService(FriendService.class).addToBlackList(account)
    .setCallback(new RequestCallback<Void>() { ... });

将用户从黑名单移除

• API 原型

java/**
 * 把用户从黑名单中移除
 *
 * @param account 用户帐号
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> removeFromBlackList(String account);

• 示例

javaNIMClient.getService(FriendService.class).removeFromBlackList(user.getAccount())
	.setCallback(new RequestCallback<Void>() { ... });

监听黑名单变更

• API 原型

java/**
 * 监听黑名单变更通知
 *
 * @param observer 观察者，参数为收到的黑名单变化通知。
 * @param register true为注册监听，false为取消监听
 */
void observeBlackListChangedNotify(Observer<BlackListChangedNotify> observer, boolean register);

• 参数说明

BlackListChangedNotify 接口说明:

返回值	BlackListChangedNotify 接口	说明
List	getAddedAccounts()	返回被加入到黑名单的用户账号
List	getRemovedAccounts()	返回移出黑名单的用户账号

• 示例

javaNIMClient.getService(FriendServiceObserve.class)
    .observeBlackListChangedNotify(blackListChangedNotifyObserver, true);

private Observer<BlackListChangedNotify> blackListChangedNotifyObserver
    = new Observer<BlackListChangedNotify>() {
    @Override
    public void onEvent(BlackListChangedNotify blackListChangedNotify) {
        List<String> addedAccounts = blackListChangedNotify.getAddedAccounts();  // 被拉黑的账号集合
        List<String> removedAccounts = blackListChangedNotify.getRemovedAccounts(); // 被移出黑名单的账号集合
        ...
    }
};

判断是否已拉黑

• API 原型

java/**
 * 判断用户是否已被拉黑
 *
 * @param account 用戶帐号
 * @return 该用户是否在黑名单列表中
 */
boolean isInBlackList(String account);

• 示例

javaboolean black = NIMClient.getService(FriendService.class).isInBlackList(account);

免打扰

云信支持对用户设置免打扰，收到该用户发来的消息时，云信范围内不再进行通知栏、振动与响铃在内的提醒。个人用户的消息提醒设置支持多端同步。

获取免打扰列表

• API 原型

java/**
 * 获取所有不需要进行消息提醒的账号列表(免打扰帐号列表）
 *
 * @return 不需要进行消息提醒的帐号集合
 */
List<String> getMuteList();

• 示例

javaList<String> accounts = NIMClient.getService(FriendService.class).getMuteList();

设置免打扰

• API 原型

java/**
 * 设置免打扰
 *
 * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用，如果出错，会有具体的错误代码。
 */
InvocationFuture<Void> setMessageNotify(String account, boolean notify);

• 参数说明

参数	说明
account	要设置消息提醒的帐号
notify	是否提醒该用户发来的消息，false 为不提醒

• 示例

javaNIMClient.getService(FriendService.class).setMessageNotify(account, checkState)
	.setCallback(new RequestCallback<Void>() {
		@Override
		public void onSuccess(Void param) {
			if (checkState) {
				Toast.makeText(UserProfileActivity.this, "开启消息提醒", Toast.LENGTH_SHORT).show();
			} else {
				Toast.makeText(UserProfileActivity.this, "关闭消息提醒", Toast.LENGTH_SHORT).show();
			}
});

监听免打扰列表变更

• API 原型

java/**
 * 监听免打扰列表变更通知
 *
 * @param observer 观察者，参数为免打扰列表变更通知。
 * @param register true为注册监听，false为取消监听
 */
void observeMuteListChangedNotify(Observer<MuteListChangedNotify> observer, boolean register);

• 参数说明

MuteListChangedNotify 接口说明:

返回值	MuteListChangedNotify 接口	说明
String	getAccount()	免打扰发生变化的用户
boolean	isMute()	该用户是否被免打扰

• 示例

javaNIMClient.getService(FriendServiceObserve.class).observeMuteListChangedNotify(
    new Observer<MuteListChangedNotify>() {
        @Override
        public void onEvent(MuteListChangedNotify notify) {
            // notify.isMute() 是否被免打扰
        }
    }, register);

判断是否免打扰

• API 原型

java/**
 * 判断用户是否需要消息提醒/免打扰
 *
 * @param account 用户帐号
 * @return true表示需要提醒；false表示免打扰
 */
boolean isNeedMessageNotify(String account);

• 示例

javaboolean notice = NIMClient.getService(FriendService.class).isNeedMessageNotify(account);