Docs Overview/
Chat/
SDK/
JavaScript/
用户/
管理好友/

管理好友

功能描述

SDK 支持好友的管理，用户可以主动添加、删除好友，也可以设置仅针对好友才能发送消息。
说明：
1. IM SDK 在发送单聊消息的时候，默认不检查好友关系。在客服场景中，如果用户需要先加客服为好友才能进行沟通非常不方便，因此该默认设置常用于在线客服等场景。如需实现“先加好友，再发消息”的交互体验，您可以在 Chat Console > Applications > Your App > Chat > Configuration > Login and Message > Relationship Check 中开启"发送单聊消息检查关系链"。开启后，用户只能给好友发送消息，当用户给非好友发消息时，SDK 会报 20009 错误码。

获取好友列表

获取 SDK 缓存的好友列表。当好友列表有更新时，SDK 会派发事件 TencentCloudChat.EVENT.FRIEND_LIST_UPDATED。
接口
chat.getFriendList();
参数
无
返回值
Promise
示例
let promise = chat.getFriendList();
promise.then(function(imResponse) {
  const friendList = imResponse.data; // 好友列表
}).catch(function(imError) {
  console.warn('getFriendList error:', imError); // 获取好友列表失败的相关信息
});

添加好友

接口
chat.addFriend(options);
参数
参数 options 为 Object 类型，包含的属性值如下：
Name
Type
Description
to
String
用户 ID
source
String
好友来源。加好友来源字段包含前缀和关键字两部分；
加好友来源字段的前缀是：AddSource_Type_ ；
关键字：必须是英文字母，且长度不得超过 8 字节，建议用一个英文单词或该英文单词的缩写。
示例：加好友来源的关键字是 Android，则加好友来源字段是：AddSource_Type_Android
wording
String | undefined
加好友附言，长度最长不得超过 256 个字节
type
String | undefined
加好友方式（默认双向加好友方式）：
TencentCloudChat.TYPES.SNS_ADD_TYPE_SINGLE 单向加好友（单向好友：用户 A 的好友表中有用户 B，但 B 的好友表中却没有 A）
TencentCloudChat.TYPES.SNS_ADD_TYPE_BOTH 双向加好友（双向好友：用户 A 的好友表中有用户 B，B 的好友表中也有 A）
remark
String | undefined
好友备注，备注长度最长不得超过 96 个字节
groupName
String | undefined
分组名，分组名长度不得超过 30 个字节
返回值
Promise
示例
// 添加好友
let promise = tim.addFriend({
  to: 'user1',
  source: 'AddSource_Type_Web',
  remark: '小橙子',
  groupName: '好友',
  wording: '我是 user0',
  type: TencentCloudChat.TYPES.SNS_ADD_TYPE_BOTH,
});
promise.then(function(imResponse) {
  // 添加好友的请求发送成功
  const { code } = imResponse.data;
  if (code === 30539) {
    // 30539 说明 user1 设置了【需要经过自己确认对方才能添加自己为好友】
    // 此时 SDK 会触发 TencentCloudChat.EVENT.FRIEND_APPLICATION_LIST_UPDATED 事件
  } else if (code === 0) {
    // 0 说明 user1 设置了【允许任何人添加自己为好友】
    // 此时 SDK 会触发 TencentCloudChat.EVENT.FRIEND_LIST_UPDATED 事件
  }
}).catch(function(imError) {
  console.warn('addFriend error:', imError); // 添加好友失败的相关信息
});

删除好友

删除好友，支持单向删除好友和双向删除好友。
说明：
1. userIDList 建议一次最大 100 个，因为数量过多可能会导致数据包太大被后台拒绝，后台限制数据包最大为 1M。
接口
chat.deleteFriend(options);
参数
参数 options为 Object 类型，包含的属性值如下：
Name
Type
Description
userIDList
Array
待删除的好友的 userID 列表，单次请求的 userID 数不得超过100
type
String | undefined
删除模式（默认双向删除好友）：
TencentCloudChat.TYPES.SNS_DELETE_TYPE_SINGLE 单向删除（只将 B 从 A 的好友表中删除，但不会将 A 从 B 的好友表中删除）
TencentCloudChat.TYPES.SNS_DELETE_TYPE_BOTH 双向删除（将 B 从 A 的好友表中删除，同时将 A 从 B 的好友表中删除）
返回值
Promise
示例
let promise = chat.deleteFriend({
  userIDList: ['user1','user2'],
  type: TencentCloudChat.TYPES.SNS_DELETE_TYPE_BOTH
});
promise.then(function(imResponse) {
  const { successUserIDList, failureUserIDList } = imResponse.data;
  // 删除成功的 userIDList
  successUserIDList.forEach((item) => {
    const { userID } = item;
  });
  // 删除失败的 userIDList
  failureUserIDList.forEach((item) => {
    const { userID, code, message } = item;
  });
  // 如果好友列表有变化，则 SDK 会触发 TencentCloudChat.EVENT.FRIEND_LIST_UPDATED 事件
}).catch(function(imError) {
  console.warn('removeFromFriendList error:', imError);
});

检查好友关系

接口
chat.checkFriend(options);
参数
参数 options为 Object类型，包含的属性值如下：
Name
Type
Description
userIDList
Array
要校验的 userID 列表，单次请求的 userID 数不得超过1000
type
String | undefined
校验模式（默认双向校验好友关系）：
TencentCloudChat.TYPES.SNS_CHECK_TYPE_SINGLE 单向校验好友关系（只会检查 A 的好友表中是否有 B，不会检查 B 的好友表中是否有 A）
TencentCloudChat.TYPES.SNS_CHECK_TYPE_BOTH 双向校验好友关系（既会检查 A 的好友表中是否有 B，也会检查 B 的好友表中是否有 A）
返回值
Promise
示例
let promise = chat.checkFriend({
  userIDList: ['user0','user1'],
  type: TencentCloudChat.TYPES.SNS_CHECK_TYPE_BOTH,
});
promise.then(function(imResponse) {
  const { successUserIDList, failureUserIDList } = imResponse.data;
  // 校验成功的 userIDList
  successUserIDList.forEach((item) => {
    const { userID, code, relation } = item; // 此时 code 始终为0
    // 单向校验好友关系时可能的结果有：
    // - relation: TencentCloudChat.TYPES.SNS_TYPE_NO_RELATION A 的好友表中没有 B，
    // 但无法确定 B 的好友表中是否有 A
    // - relation: TencentCloudChat.TYPES.SNS_TYPE_A_WITH_B A 的好友表中有 B，但无法确定 B 的好友表中是否有 A
    // 双向校验好友关系时可能的结果有：
    // - relation: TencentCloudChat.TYPES.SNS_TYPE_NO_RELATION A 的好友表中没有 B，B 的好友表中也没有 A
    // - relation: TencentCloudChat.TYPES.SNS_TYPE_A_WITH_B A 的好友表中有 B，但 B 的好友表中没有 A
    // - relation: TencentCloudChat.TYPES.SNS_TYPE_B_WITH_A A 的好友表中没有 B，但 B 的好友表中有 A
    // - relation: TencentCloudChat.TYPES.SNS_TYPE_BOTH_WAY A 的好友表中有 B，B 的好友表中也有 A
  });
  // 校验失败的 userIDList
  failureUserIDList.forEach((item) => {
    const { userID, code, message } = item;
  });
}).catch(function(imError) {
  console.warn('checkFriend error:', imError);
});

获取好友资料

获取指定好友的全量好友数据（包含好友标配字段和好友自定义字段）和全量资料数据（包含资料标配字段和资料自定义字段）。
接口
chat.getFriendProfile(options);
参数
参数 options为 Object类型，包含的属性值如下：
Name
Type
Description
userIDList
Array
好友的 userID 列表
返回值
Promise
示例
// 获取好友标配字段、好友自定义字段、资料标配字段、资料自定义字段
let promise = chat.getFriendProfile({
  userIDList: ['user0','user1']
});
promise.then(function(imResponse) {
  const { friendList, failureUserIDList } = imResponse.data;
  friendList.forEach((friend) => {
    // Friend 对象
  });
  // 失败的 userIDList
  failureUserIDList.forEach((item) => {
    const { userID, code, message } = item;
  });
}).catch(function(imError) {
  console.warn('getFriendProfile error:', imError); // 获取失败
});

更新好友

更新好友的关系链数据，只支持好友备注、关系链自定义字段的更新操作。
接口
chat.updateFriend(options);
参数
参数 options为 Object类型，包含的属性值如下：
Name
Type
Description
userID
String
要更新的好友 userID
remark
String
好友备注，备注长度最长不得超过 96 个字节
friendCustomField
Array.<Object>
好友自定义字段键值对集合，可根据业务侧需要使用
返回值
Promise
示例
// 更新好友备注
let promise = chat.updateFriend({
  userID: 'user1',
  remark: 'helloworld'
});
promise.then(function(imResponse) {
  console.log(imResponse.data); // Friend 实例
}).catch(function(imError) {
  console.warn('getFriendProfile error:', imError); // 更新失败
});
// 更新好友自定义字段
let promise = chat.updateFriend({
  userID: 'user1',
  friendCustomField: [
    // 好友自定义字段必须以 Tag_SNS_Custom 为前缀
    { key: 'Tag_SNS_Custom_test1', value: 'hello' },
    { key: 'Tag_SNS_Custom_test2', value: 'world' },
  ]
});
promise.then(function(imResponse) {
  console.log(imResponse.data); // Friend 实例
}).catch(function(imError) {
  console.warn('getFriendProfile error:', imError); // 更新失败
});

获取好友申请列表

获取 SDK 缓存的好友申请列表。当好友申请列表有更新时，SDK 会派发事件 TencentCloudChat.EVENT.FRIEND_APPLICATION_LIST_UPDATED
说明：
1. 如果您的个人资料（通过 getMyProfile 接口获取）中 allowType设置为 TencentCloudChat.TYPES.ALLOW_TYPE_ALLOW_ANY（当被人加好友时：允许任何人添加自己为好友），此接口将无法拉取到好友申请列表
接口
chat.getFriendApplicationList();
参数
无
返回值
Promise
示例
let promise = chat.getFriendApplicationList();
promise.then(function(imResponse) {
  // friendApplicationList - 好友申请列表 - [FriendApplication]
  // FriendApplication 数据结构详情请参考 https://web.sdk.qcloud.com/im/doc/v3/zh-cn/FriendApplication.html
  // unreadCount - 好友申请的未读数
  // const { friendApplicationList, unreadCount } = imResponse.data;
});

同意好友申请

接口
chat.acceptFriendApplication(options);
参数
参数 options为 Object类型，包含的属性值如下：
Name
Type
Description
userID
String
待同意的好友申请的 userID
remark
String
好友备注，备注长度最长不得超过 96 个字节
type
String
类型：
1. TencentCloudChat.TYPES.SNS_APPLICATION_AGREE 同意添加单向好友
2. TencentCloudChat.TYPES.SNS_APPLICATION_AGREE_AND_ADD 同意并添加为双向好友

返回值
Promise
示例
let promise = chat.acceptFriendApplication({
  userID: 'user1',
  remark: '客服小亮',
  type: TencentCloudChat.TYPES.SNS_APPLICATION_AGREE_AND_ADD
});
promise.then(function(imResponse) {
  // 同意好友成功后，SDK 会触发 TencentCloudChat.EVENT.FRIEND_APPLICATION_LIST_UPDATED 事件
}).catch(function(imError) {
  console.warn('acceptFriendApplication error:', imError);
});

拒绝好友申请

接口
chat.refuseFriendApplication(options);
参数
参数 options为 Object类型，包含的属性值如下：
Name
Type
Description
userID
String
的好友申请的 userID
返回值
Promise
示例
let promise = chat.refuseFriendApplication({
  userID: 'user1',
});
promise.then(function(imResponse) {
// 拒绝成功后，SDK 会触发 TencentCloudChat.EVENT.FRIEND_APPLICATION_LIST_UPDATED 事件
}).catch(function(imError) {
  console.warn('refuseFriendApplication error:', imError);
});

删除好友申请

接口
chat.deleteFriendApplication(options);
参数
参数 options为 Object类型，包含的属性值如下：
Name
Type
Description
userID
String
待删除的好友申请的 userID
type
String
好友申请的类型：
TencentCloudChat.TYPES.SNS_APPLICATION_SENT_TO_ME 别人发给我的好友申请
TencentCloudChat.TYPES.SNS_APPLICATION_SENT_BY_ME 我发给别人的好友申请
返回值
Promise
示例
let promise = chat.deleteFriendApplication({
  userID: 'user1',
  type: TencentCloudChat.TYPES.SNS_APPLICATION_SENT_TO_ME
});
promise.then(function(imResponse) {
  // 删除成功后，SDK 会触发 TencentCloudChat.EVENT.FRIEND_APPLICATION_LIST_UPDATED 事件
}).catch(function(imError) {
  console.warn('deleteFriendApplication error:', imError);
});

上报好友申请已读

接口
chat.setFriendApplicationRead();
参数
无
返回值
Promise
示例
// 上报好友申请已读
let promise = chat.setFriendApplicationRead();
promise.then(function(imResponse) {
  // 已读上报成功
}).catch(function(imError) {
  console.warn('setFriendApplicationRead error:', imError);
});