tencent cloud

文档反馈

JavaScript

最后更新时间:2024-11-15 10:51:59

    功能描述

    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);
    参数
    参数 optionsObject 类型,包含的属性值如下:
    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);
    参数
    参数 optionsObject类型,包含的属性值如下:
    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);
    参数
    参数 optionsObject类型,包含的属性值如下:
    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);
    参数
    参数 optionsObject类型,包含的属性值如下:
    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);
    参数
    参数 optionsObject类型,包含的属性值如下:
    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);
    参数
    参数 optionsObject类型,包含的属性值如下:
    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);
    参数
    参数 optionsObject类型,包含的属性值如下:
    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);
    });
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持