本文档提供好友关系的功能使用说明。你可以通过好友关系功能模块实现用户之间的联系关系建立，无需自行建设好友业务逻辑。

API 接口详细文档参看 Android API 参考、iOS API 参考、Web API 参考、微信小程序 API 参考。

参看构建基础应用集成使用 IM SDK，版本 v1.2.0 以上。
Web 端需要在实例化时传入 ContactPlugin。

import { BytedIM, ContactPlugin } from '@volcengine/im-web-sdk';
const bytedIMInstance = new BytedIM({/* 省略 options */}, [ContactPlugin]);
typescript

使用 applyFriend 接口发起好友申请。成功调用后，对方会收到好友申请的事件监听，参看好友事件监听。

BIMApplyInfo apply = new BIMApplyInfo();
apply.setUid(uid);    //uid 为被申请用户的用户 ID

BIMClient.getInstance().getService(BIMContactExpandService.class).applyFriend(apply, new BIMResultCallback<BIMFriendApplyInfo>() {
    @Override
    public void onSuccess(BIMFriendApplyInfo friendApplyInfo) {
          //申请成功
    }

    @Override
    public void onFailed(BIMErrorCode code) {
        //申请失败
    }
});
java

BIMApplyInfo *applyInfo = [[BIMApplyInfo alloc] init];
applyInfo.uid = uid; //uid 为被申请用户的用户 ID
[[BIMClient sharedInstance] applyFriend:applyInfo completion:^(BIMError * _Nullable error) {
    
}];
objectivec

await bytedIMInstance.applyFriend({ userId: inputUserId });
TypeScript

添加好友事件监听，监听好友申请、好友通过、好友删除等事件。

BIMFriendListener listener = new BIMFriendListener() {
    @Override
    public void onFriendApply(BIMFriendApplyInfo applyInfo) {
        //收到好友申请
    }

    @Override
    public void onFriendDelete(BIMFriendInfo friendInfo) {
        //好友删除
    }

    @Override
    public void onFriendAdd(BIMFriendInfo friendInfo) {
        //新增好友
    }

    @Override
    public void onFriendAgree(BIMFriendApplyInfo applyInfo) {
        //同意好友申请
    }

    @Override
    public void onFriendRefuse(BIMFriendApplyInfo applyInfo) {
        //拒绝好友申请
    }

    @Override
    public void onFriendApplyUnreadCountChanged(int count) {
        //好友申请未读数变化
    }
}
//添加监听
BIMClient.getInstance().getService(BIMContactExpandService.class).addFriendListener(listener);

//移除监听
BIMClient.getInstance().getService(BIMContactExpandService.class).removeFriendListener(listener)
java

[[BIMClient sharedInstance] addFriendListener:id<BIMFriendListener>listener];
[[BIMClient sharedInstance] removeFriendListener:id<BIMFriendListener>listener];
/**
 * @type callback
 * @brief 申请成为好友回调。
 */
- (void)onFriendApply:(BIMFriendApplyInfo *)applyInfo{}

/**
 * @type callback
 * @brief 删除好友回调。
 */
- (void)onFriendDelete:(long long)uid{}

/**
 * @type callback
 * @brief 好友新增（同意好友）。
 */
- (void)onFriendAdd:(BIMFriendInfo *)friendInfo{}

/**
 * @brief 好友同意
 * @type callback
 * @param applyInfo 好友申请信息。
 */
- (void)onFriendApplyAgree:(BIMFriendApplyInfo *)applyInfo{}

/**
 * @type callback
 * @brief 拒绝好友回调。
 * @param applyInfo 好友申请信息。
 */
- (void)onFriendApplyRefuse:(BIMFriendApplyInfo *)applyInfo{}

/**
 * @type callback
 * @brief 好友申请未读数变化。
 * @param count 变化后的未读数。
 */
- (void)onFriendApplyUnreadCountChanged:(long long)count{}
objectivec

// 事件名在 IMEvent.Friend*，所有事件参见文档 https://www.volcengine.com/docs/6348/293492#imevent
// 以上面发起好友申请为例，接收方通过订阅 IMEvent.FriendApply 监听新的好友申请
const subscription = bytedIMInstance.event.subscribe(IMEvent.FriendApply, callback);
// 退订上面的订阅
bytedIMInstance.event.unsubscribe(IMEvent.FriendApply, subscription);
TypeScript

当前用户收到好友申请后，可选择同意或者拒绝此好友申请，方法成功调用后会发送回应信息给申请用户。

BIMReplyInfo apply = new BIMReplyInfo();
apply.setUid(friendApplyInfo.getFromUid());
apply.setReplyType(BIMFriendReplyType.BIM_FRIEND_REPLY_AGREE);

BIMClient.getInstance().getService(BIMContactExpandService.class).replyFriendApply(apply, new BIMResultCallback<BIMFriendApplyInfo>() {
    @Override
    public void onSuccess(BIMFriendApplyInfo friendApplyInfo) {
         //回应成功
    }

    @Override
    public void onFailed(BIMErrorCode code) {
         //回应失败
    }
});
java

BIMReplyInfo *replyInfo = [[BIMReplyInfo alloc] init];
replyInfo.uid = uid;
replyInfo.replyType = BIM_FRIEND_REPLY_AGREE;

[[BIMClient sharedInstance] replyFriendApply:replyInfo completion:^(BIMError * _Nullable error) {

}];
objectivec

// 需要从包中引入 ReplyFriendAttitude，接受请求
await bytedIMInstance.replyFriendApply({ userId: i.fromUserId, attitude: ReplyFriendAttitude.Accept });
// 拒绝请求
await bytedIMInstance.replyFriendApply({ userId: i.fromUserId, attitude: ReplyFriendAttitude.Reject });
TypeScript

其中 replyType 包括如下枚举类型

public enum BIMFriendReplyType {
    /**
     * @brief 未知
     */
    BIM_FRIEND_REPLY_UNKNOWN(-1),
    /**
     * @brief 同意状态
     */
    BIM_FRIEND_REPLY_AGREE(0),
    /**
     * @brief 拒绝状态
     */
    BIM_FRIEND_REPLY_REFUSE(1);
}
java

可以通过此接口按照由新到旧的顺序获取好友申请列表，包括离线期间收到的好友申请。

// 分页拉取，首页拉取可以传入 0 
BIMClient.getInstance().getService(BIMContactExpandService.class).getFriendApplyList(cusror, 20, new BIMResultCallback<com.bytedance.im.user.api.model.BIMFriendApplyListResult>() {
    @Override
    public void onSuccess(BIMFriendApplyListResult bimFriendApplyListResult) {
        // 拉取成功
        bimFriendApplyListResult.isHasMore();             //是否还有更多
        bimFriendApplyListResult.getApplyFriendList();    //好友申请列表
        bimFriendApplyListResult.getNextCursor();        //下一页起始游标
    }

    @Override
    public void onFailed(BIMErrorCode code) {
         // 拉取失败
    }
});
java

[[BIMClient sharedInstance] getFriendApplyList:self.currCursor limit:self.pageSize completion:^(NSArray<BIMFriendApplyInfo *> * _Nullable infos, BOOL hasMore, long long nextCursor, BIMError * _Nullable error) {
    if (infos.count) {
        self.currCursor = nextCursor;
    }    
}];
objectivec

const resp = await bytedIMInstance.getFriendReceiveApplyList({});
console.log(resp.list);
TypeScript

可以通过此接口获取所有当前好友信息。

BIMClient.getInstance().getService(BIMContactExpandService.class).getFriendList( new BIMResultCallback<List<BIMFriendInfo>>() {

    @Override
    public void onSuccess(List<BIMFriendInfo> bimFriendInfos) {
       //拉取成功
    }

    @Override
    public void onFailed(BIMErrorCode code) {
        //拉取失败
    }
});
java

[[BIMClient sharedInstance] getFriendListCompletion:^(NSArray<BIMFriendInfo *> * _Nullable infos, BIMError * _Nullable error) {

}];
objectivec

const resp = await bytedIMInstance.getFriendList({});
 console.log(resp.list);
TypeScript

未读的好友申请有两种获取方式，被动监听和主动获取。其中被动监听参看好友事件监听 BIMFriendListener 中 onFriendApplyUnreadCountChanged 方法回调。主动获取好友申请未读数示例代码如下。

BIMClient.getInstance().getService(BIMContactExpandService.class).getFriendApplyUnreadCount(new BIMResultCallback<Integer>() {
    @Override
    public void onSuccess(Integer integer) {
        //获取成功 好友未读数
    }

    @Override
    public void onFailed(BIMErrorCode code) {
        //获取失败
    }
});
java

[[BIMClient sharedInstance] getFriendApplyUnreadCount:^(long long unreadCount, BIMError * _Nullable error) {

}];
objectivec

// Web SDK 直接通过请求列表 API 请求主动获取
const resp = await bytedIMInstance.getFriendReceiveApplyList({});
return resp.unreadCount;
TypeScript

好友关系还支持如下功能，详情参看 API 文档。

• 删除好友
• 黑名单功能
• 好友备注功能