tencent cloud

文档反馈

JavaScript

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

    功能描述

    群组管理功能指的是搜索群组、创建群组、加入群组、获取已加入的群组、退出群组和解散群组等。

    群事件监听

    示例
    let onGroupListUpdated = function(event) {
    console.log(event.data);// 包含 Group 实例的数组
    };
    chat.on(TencentCloudChat.EVENT.GROUP_LIST_UPDATED, onGroupListUpdated);

    搜索群组

    说明:
    TencentCloudChat.TYPES.GRP_WORK 类型的群组(好友工作群)不能被搜索。
    接口
    chat.searchGroupByID(groupID);
    参数
    Name
    Type
    Description
    groupID
    String
    群组 ID
    返回值
    Promise
    示例
    let promise = chat.searchGroupByID('group1');
    promise.then(function(imResponse) {
    const group = imResponse.data.group; // 群组信息
    }).catch(function(imError) {
    console.warn('searchGroupByID error:', imError); // 搜素群组失败的相关信息
    });

    创建群组

    说明:
    1. 该接口创建 TencentCloudChat.TYPES.GRP_AVCHATROOM(直播群) 后,需调用 joinGroup 接口加入群组后,才能进行消息收发流程。
    2. 该接口可以创建支持话题的社群。
    接口
    chat.createGroup(options);
    参数
    参数 optionsObject类型,包含的属性值如下:
    Name
    Type
    Description
    name
    String
    群名称,最长30字节
    type
    String
    群组类型,包括:
    TencentCloudChat.TYPES.GRP_WORK(好友工作群,默认)
    TencentCloudChat.TYPES.GRP_PUBLIC(陌生人社交群)
    TencentCloudChat.TYPES.GRP_MEETING(临时会议群)
    TencentCloudChat.TYPES.GRP_AVCHATROOM(直播群)
    TencentCloudChat.TYPES.GRP_COMMUNITY(社群)
    groupID
    String | undefined
    群组ID。不填该字段时,会自动为群组创建一个唯一的群 ID
    introduction
    String | undefined
    群简介,最长240字节
    notification
    String | undefined
    群公告,最长300字节
    avatar
    String | undefined
    群头像 URL,最长100字节
    maxMemberNum
    Number | undefined
    最大群成员数量,缺省时的默认值:
    好友工作群是200
    陌生人社交群是2000
    临时会议群是10000
    直播群无限制
    joinOption
    String
    申请加群处理方式。
    TencentCloudChat.TYPES.JOIN_OPTIONS_FREE_ACCESS (自由加入)
    TencentCloudChat.TYPES.JOIN_OPTIONS_NEED_PERMISSION (需要验证)
    TencentCloudChat.TYPES.JOIN_OPTIONS_DISABLE_APPLY (禁止加群)
    说明:
    TencentCloudChat.TYPES.GRP_WORK, TencentCloudChat.TYPES.GRP_MEETING, TencentCloudChat.TYPES.GRP_AVCHATROOM 类型群组的该属性不允许修改。好友工作群禁止申请加群,临时会议群和直播群自由加入。
    inviteOption
    String
    邀请进群处理方式。 TencentCloudChat.TYPES.INVITE_OPTIONS_FREE_ACCESS(无需审批直接邀请进群) TencentCloudChat.TYPES.INVITE_OPTIONS_NEED_PERMISSION(需要群主/群管理员验证) TencentCloudChat.TYPES.INVITE_OPTIONS_DISABLE_INVITE (禁止邀请)
    说明:
    TencentCloudChat.TYPES.GRP_AVCHATROOM 类型的群组该属性不支持设置,其他类型群组均支持。
    memberList
    Array | undefined
    初始群成员列表,最多 100 个。创建直播群时不能添加成员。数组元素结构如下:
    userID --- String --- 必填,群成员的 userID
    role --- String --- 成员身份,可选值只有 Admin,表示添加该成员并设其为管理员
    memberCustomField --- Array
    groupCustomField
    Array | undefined
    群自定义字段。默认情况是没有的,开通群组维度的自定义字段请参见 自定义字段
    isSupportTopic
    Boolean
    创建支持话题的社群时必填,
    true - 创建支持话题的社群
    false - 创建普通社群
    返回值
    Promise
    示例
    // 创建好友工作群
    let promise = chat.createGroup({
    type: TencentCloudChat.TYPES.GRP_WORK,
    name: 'WebSDK',
    memberList: [{
    userID: 'user1',
    // 群成员维度的自定义字段,默认情况是没有的,需要开通,详情请参阅自定义字段
    memberCustomField: [{key: 'group_member_test', value: 'test'}]
    }, {
    userID: 'user2'
    }] // 如果填写了 memberList,则必须填写 userID
    });
    promise.then(function(imResponse) { // 创建成功
    console.log(imResponse.data.group); // 创建的群的资料
    // 创建群时指定了成员列表,但是成员中存在超过了“单个用户可加入群组数”限制的情况
    // 一个用户 userX 最多允许加入 N 个群,如果已经加入了 N 个群,此时创建群再指定 userX 为群成员,则 userX 不能正常加群
    // SDK 将 userX 的信息放入 overLimitUserIDList,供接入侧处理
    console.log(imResponse.data.overLimitUserIDList); // 超过了“单个用户可加入群组数”限制的用户列表
    }).catch(function(imError) {
    console.warn('createGroup error:', imError); // 创建群组失败的相关信息
    });
    // 创建支持话题的社群
    let promise = chat.createGroup({
    type: TencentCloudChat.TYPES.GRP_COMMUNITY,
    name: 'WebSDK',
    isSupportTopic: true,
    });
    promise.then(function(imResponse) { // 创建成功
    console.log(imResponse.data.group); // 创建的群的资料
    }).catch(function(imError) {
    console.warn('createGroup error:', imError); // 创建群组失败的相关信息
    });
    // 创建一个群,设置 inviteOption 为
    let promise = chat.createGroup({
    type: TencentCloudChat.TYPES.GRP_PUBLIC,
    name: 'WebSDK',
    inviteOption: TencentCloudChat.TYPES.INVITE_OPTIONS_NEED_PERMISSION,
    });
    promise.then(function(imResponse) {
    console.log(imResponse.data.group);
    }).catch(function(imError) {
    console.warn('createGroup error:', imError);
    });

    加入群组

    不同类型的群组,加入群组的方法不同:
    类型
    加群方法
    好友工作群(Work)
    必须由其他群成员邀请
    陌生人社交群(Public)
    用户申请,群主或管理员审批
    邀请进群,默认不支持,可修改邀请选项支持
    临时会议群(Meeting)
    用户可随意加入
    邀请进群,默认不支持,可修改邀请选项支持
    社群(Community)
    用户可随意加入
    邀请进群,默认不支持,可修改邀请选项支持
    直播群(AVChatRoom)
    用户可随意加入
    说明:
    1. 好友工作群不允许申请加群,只能通过 addGroupMember 方式添加。
    2. 同一用户同时只能加入一个直播群。例如,用户已在直播群 A 中,再加入直播群 B,SDK 会先退出直播群 A,然后加入直播群 B。
    3. 加群前可通过 searchGroupByID接口搜索群是否存在。
    接口
    chat.joinGroup(options);
    参数
    参数 options Object 类型,包含的属性值如下:
    Name
    Type
    Description
    groupID
    String
    群组 ID
    applyMessage
    String | undefined
    附言
    返回值
    Promise
    示例
    let promise = chat.joinGroup({ groupID: 'group1' });
    promise.then(function(imResponse) {
    switch (imResponse.data.status) {
    case TencentCloudChat.TYPES.JOIN_STATUS_WAIT_APPROVAL: // 等待管理员同意
    break;
    case TencentCloudChat.TYPES.JOIN_STATUS_SUCCESS: // 加群成功
    console.log(imResponse.data.group); // 加入的群组资料
    break;
    case TencentCloudChat.TYPES.JOIN_STATUS_ALREADY_IN_GROUP: // 已经在群中
    break;
    default:
    break;
    }
    }).catch(function(imError){
    console.warn('joinGroup error:', imError); // 申请加群失败的相关信息
    });

    获取已加入的群组

    说明:
    1. 该接口返回 SDK 从云端已同步的群组列表,不包含 TencentCloudChat.TYPES.GRP_AVCHATROOM(直播群)类型的群组。
    2. 接口返回的群组列表,只包含群的基础资料(群类型、群名称、群头像、@信息列表)。
    3. 如果想要获取群的详细资料,请使用 getGroupProfile
    接口
    chat.getGroupList();
    参数
    返回值
    Promise
    示例
    // 该接口默认只会拉取这些资料:群类型、群名称、群头像、最后一条消息的时间。
    let promise = chat.getGroupList();
    promise.then(function(imResponse) {
    console.log(imResponse.data.groupList); // 群组列表
    }).catch(function(imError) {
    console.warn('getGroupList error:', imError); // 获取群组列表失败的相关信息
    });

    退出群组

    说明:
    1. 群主只能退出好友工作群,退出后该好友工作群无群主。
    2. 退出群组后,若登录态未失效,SDK 仍会保留对应的群会话,如果您想删除会话,请使用 deleteConversation
    接口
    chat.quitGroup(groupID);
    参数
    Name
    Type
    Description
    groupID
    String
    群组 ID
    返回值
    Promise
    示例
    let promise = chat.quitGroup('group1');
    promise.then(function(imResponse) {
    console.log(imResponse.data.groupID); // 退出成功的群 ID
    }).catch(function(imError){
    console.warn('quitGroup error:', imError); // 退出群组失败的相关信息
    });

    解散群组

    说明:
    1. 群主不能解散好友工作群。
    2. 退出群组后,若登录态未失效,SDK 仍会保留对应的群会话,如果您想删除会话,请使用 deleteConversation
    接口
    chat.dismissGroup(groupID);
    参数
    Name
    Type
    Description
    groupID
    String
    群组 ID
    返回值
    Promise
    示例
    let promise = chat.dismissGroup('group1');
    promise.then(function(imResponse) { // 解散成功
    console.log(imResponse.data.groupID); // 被解散的群组 ID
    }).catch(function(imError) {
    console.warn('dismissGroup error:', imError); // 解散群组失败的相关信息
    });

    转让群组

    说明:
    只有群主拥有转让的权限。
    TencentCloudChat.TYPES.GRP_AVCHATROOM(直播群)类型的群组不能转让。
    接口
    chat.changeGroupOwner(options);
    参数
    参数 options 为 Object 类型,包含的属性值如下:
    Name
    Type
    Description
    groupID
    String
    待转让的群组 ID
    newOwnerID
    String
    新群主的 ID
    返回值
    Promise
    示例
    let promise = chat.changeGroupOwner({
    groupID: 'group1',
    newOwnerID: 'user2'
    });
    promise.then(function(imResponse) { // 转让成功
    console.log(imResponse.data.group); // 群组资料
    }).catch(function(imError) { // 转让失败
    console.warn('changeGroupOwner error:', imError); // 转让群组失败的相关信息
    });

    获取加群申请和邀请进群申请列表

    接口
    chat.getGroupApplicationList();
    参数
    返回值
    Promise
    示例
    let promise = chat.getGroupApplicationList();
    promise.then(function(imResponse) {
    const { applicationList } = imResponse.data;
    applicationList.forEach((item) => {
    // item.applicant - 申请者 userID
    // item.applicantNick - 申请者昵称
    // item.groupID - 群 ID
    // item.groupName - 群名称
    // item.applicationType - 申请类型:0 加群申请,2 邀请进群申请
    // item.userID - applicationType = 2时,是被邀请用户的 userID
    // item.note - 附言信息,邀请加群暂不支持,返回为空字符串
    // 接入侧可调用 handleGroupApplication 接口同意或拒绝加群申请
    chat.handleGroupApplication({
    handleAction: 'Agree',
    application: {...item},
    });
    });
    }).catch(function(imError) {
    console.warn('getGroupApplicationList error:', imError);
    });

    处理申请加群和邀请进群(同意或拒绝)

    说明:
    1. 如果一个群有多位群管理员,当有人申请加群时,所有在线的群管理员都会收到申请加群 的群系统通知。如果某位群管理员处理了这个申请(同意或者拒绝),则其他管理员无法重复处理(即不能修改处理的结果)。
    2. 如果一个群有多群位管理员,当有人邀请用户进群时,所有在线的群管理员都会收到邀请进群 的群系统通知。如果某位群管理员通过未决列表处理了这个申请(同意或者拒绝),则其他管理员无法重复处理(即不能修改处理的结果)。
    
    接口
    chat.handleGroupApplication(options);
    参数
    参数 optionsObject类型,包含的属性值如下:
    Name
    Type
    Description
    handleAction
    String
    处理结果 Agree(同意) / Reject(拒绝)
    handleMessage
    String | undefined
    附言
    message
    Message
    对应群系统通知的消息实例
    application
    Object
    加群申请
    返回值
    Promise
    示例
    // 通过系统通知处理加群申请
    let promise = chat.handleGroupApplication({
    handleAction: 'Agree',
    handleMessage: '欢迎欢迎',
    message: message // 申请加群群系统通知的消息实例
    });
    promise.then(function(imResponse) {
    console.log(imResponse.data.group); // 群组资料
    }).catch(function(imError){
    console.warn('handleGroupApplication error:', imError); // 错误信息
    });
    // 通过获取未决列表处理加群申请
    let promise = chat.getGroupApplicationList();
    promise.then(function(imResponse) {
    const { applicationList } = imResponse.data;
    applicationList.forEach((item) => {
    if (item.applicationType === 0) {
    chat.handleGroupApplication({
    handleAction: 'Agree',
    application: {...item},
    });
    }
    });
    }).catch(function(imError) {
    console.warn('getGroupApplicationList error:', imError);
    });
    // 通过获取未决列表处理邀请进群申请
    let promise = chat.getGroupApplicationList();
    promise.then(function(imResponse) {
    const { applicationList } = imResponse.data;
    applicationList.forEach((item) => {
    if (item.applicationType === 2) {
    chat.handleGroupApplication({
    handleAction: 'Agree',
    application: {...item},
    });
    }
    });
    }).catch(function(imError) {
    console.warn('getGroupApplicationList error:', imError);
    });
    
    联系我们

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

    技术支持

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

    7x24 电话支持