tencent cloud

即时通信 IM

动态与公告
产品动态
公告
产品简介
产品概述
基本概念
应用场景
功能介绍
账号系统
用户资料与关系链
消息管理
群组相关
公众号系统
音视频通话 Call
使用限制
购买指南
计费概述
价格说明
购买指引
续费指引
停服说明
退费说明
开发指引
Demo 专区
开通服务
体验 Demo
快速跑通
下载中心
SDK & Demo 源码
更新日志
聊天互动(含 UI)
TUIKit 组件介绍
快速开始
全功能接入
单功能接入
AI 集成
构建基础界面
更多特性
定义外观
国际化界面语言
推送服务(Push)
服务概述
名词解释
开通服务
快速跑通
厂商通道
数据统计
排查工具
客户端 API
服务端 API
推送回调
高级功能
更新日志
错误码
常见问题
智能客服
功能概述
快速入门
集成指引
管理员操作手册
客服操作手册
更多实践
直播间搭建
AI 聊天机器人方案
超大娱乐协作社群
Discord 实现指南
游戏内集成 Chat 指南
类 WhatsApp Channel 搭建方案
发送红包
Chat 应对防火墙限制相关
无 UI 集成
快速开始
集成 SDK
初始化
登录登出
消息相关
会话相关
群组相关
社群话题
用户管理
离线推送
云端搜索
本地搜索
公众号
客户端 API
JavaScript
Android
iOS & macOS
Swift
Flutter
Electron
Unity
React Native
C 接口
C++
服务端 API
生成 UserSig
REST API
第三方回调
控制台指南
新版控制台介绍
创建并升级应用
基本配置
功能配置
账号管理
群组管理
公众号管理
回调配置
用量统计
资源包查看指南
实时监控
开发辅助工具
访问管理
高级功能
常见问题
uni-app 常见问题
购买相关问题
SDK 相关问题
账号鉴权相关问题
用户资料与关系链相关问题
消息相关问题
群组相关问题
直播群相关问题
昵称头像相关问题
协议与认证
服务等级协议
安全合规认证
IM 政策
隐私政策
数据隐私和安全协议
平滑迁移方案
平滑迁移完整版
平滑迁移简化版
错误码
联系我们

JavaScript

PDF
聚焦模式
字号
最后更新时间: 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);
});


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈