tencent cloud

群组系统简介

群组系统是一个支持多人聊天的即时通信系统，群组系统所具备的基本能力包括：

• 完备的 群组管理 能力：创建/解散群组、成员管理、群组资料管理、成员资料管理等。
• 稳定可靠的消息收发能力，完善的 群组消息 管理机制：权限控制，禁言，消息回调，消息漫游等。
• 根据常见使用场景，默认配置了好友工作群（Work）、陌生人社交群（Public）、临时会议群（Meeting）、直播群（AVChatRoom）和社群（Community） 五个群组类型。
• 可拓展的群成员人数上限：
  • 好友工作群（Work）、陌生人社交群（Public）和临时会议群（Meeting）成员人数上限最高支持付费拓展到6000人，详情请参阅 价格说明。
  • 社群（Community）最高支持10万人。
  • 直播群（AVChatRoom）成员人数无上限。

注意：

• 直播群（AVChatRoom）不设成员人数上限，但如果预期群成员会出现短时间内激增的场景（例如举行大型在线活动，单群成员人数达到5万或以上等情况），请提前联系 腾讯云客服 或商务工作人员，提供 SDKAppID 和活动预期发生时间进行服务资源报备。
• 目前仅非直播群具备历史消息存储能力（体验版及专业版默认7天，旗舰版默认30天）。如需保存更长时间，您可以在 控制台 修改消息历史消息存储时长。延长历史消息存储时长是付费增值服务，具体计费说明请参考 价格说明。
• 社群（Community），娱乐协作新利器。同一社群内，既可划分不同分组、话题，将消息相互区隔，进行分层级沟通；又可容纳超大规模成员，共用一套好友关系，助您摸索出一条独特的社交扩张路径；适用于兴趣交友、游戏社交、粉丝运营、组织管理等场景。
• 社群（Community）功能支持终端 SDK 5.8.1668增强版及以上版本、Web SDK 2.17.0及以上版本，需 购买旗舰版 并在 控制台>群功能配置>社群 打开开关后方可使用。

除此之外，即时通信 IM 群组系统具备高度可定制性，具体包括：

• 自定义消息元素
• 自定义群组 ID
• 自定义话题 ID
• 自定义字段
• 自定义回调

群成员角色介绍

群组中各成员的角色及其权限如下表：

群组成员角色	描述	管理权限
普通成员	不具备管理权限的群成员	好友工作群（Work）中，普通成员具备修改群组资料的权限
管理员	由群主任命的、协助群主来管理群组的群成员，拥有一定的管理权限	修改群组基本资料 将普通群成员踢出群 将普通群成员禁言（即禁止其在一段时间内发言） 审批其他用户的入群申请 好友工作群（Work）默认不支持设置管理员
群主	群组的创建者，在群组中拥有最高的管理权限	群主具备管理员所拥有的各项权限之外，还拥有如下权限： 任命/取消管理员 将管理员踢出群组 将管理员禁言 解散群组 转让群组
App 管理员	具备管理 App 中所有群组权限的一种特殊身份，能力超过群主	App 管理员可以不是群组中的成员，但是拥有群主具备的所有权限

群组类型介绍

根据常见使用场景，默认配置了以下群组类型：

群组类型	适用场景
好友工作群（Work）	创建后仅支持已在群内的好友邀请加群，且无需被邀请方同意或群主审批，同旧版本中的 Private
陌生人社交群（Public）	创建后群主可以指定群管理员，用户搜索群 ID 发起加群申请后，需要群主或管理员审批通过才能入群
临时会议群（Meeting）	创建后可以随意进出，且支持查看入群前消息；适合用于音视频会议场景、在线教育场景等与实时音视频产品结合的场景，同旧版本中的 ChatRoom
直播群（AVChatRoom）	创建后可以随意进出，没有群成员数量上限，但不支持历史消息存储；适合与直播产品结合，用于弹幕聊天场景
社群（Community）	创建后可以随意进出，最多支持10w人，支持历史消息存储，用户搜索群 ID 发起加群申请后，无需管理员审批即可进群

群组基础能力操作差异

功能项	好友工作群（Work）	陌生人社交群（Public）	临时会议群（Meeting）	直播群（AVChatRoom）	社群（Community）
可用成员角色	群主 普通成员 App 管理员	群主 管理员 普通成员 App 管理员	群主 管理员 普通成员 App 管理员	群主 App 管理员	群主 管理员 普通成员 App 管理员
修改群基础资料的权限	普通成员 群主 App 管理员	群管理员 群主 App 管理员	群主 App 管理员	群主 App 管理员	管理员 群主 App 管理员
获取群成员信息	可获取全部群成员信息	可获取全部成员信息	可获取全部成员信息	不存储群成员信息	可获取全部成员信息
解散群	只有 App 管理员可以解散群	群主和 App 管理员可以解散群	群主和 App 管理员可以解散群	群主和 App 管理员可以解散群	群主和 App 管理员可以解散群

说明：

• 新版 SDK 已全面升级群组类型。新群组类型有好友工作群（Work）、陌生人社交群（Public）、临时会议群（Meeting）、直播群（AVChatRoom）和社群（Community）五个群组类型。旧版群组类型（Public、Private、ChatRoom、AVChatRoom）中的 Private 类型对应新群组类型 Work（好友工作群），ChatRoom 类型对应新群组类型 Meeting（临时会议群）。
• 对于好友工作群（Work），普通成员只能修改群名称、简介、公告、群头像 URL，不能修改其他群基础资料。
• 如果群类型中的角色不能满足业务需求，可以通过设置群成员 自定义字段 来增加新角色。
• 获取部分群成员的信息，常用于直播群（AVChatRoom）中只需要展示部分群成员列表的场景。

加群方式差异

功能项	好友工作群（Work）	陌生人社交群（Public）	临时会议群（Meeting）	直播群（AVChatRoom）	社群（Community）
是否支持精确搜索群ID加群	不支持	支持	支持	支持	支持
是否支持模糊搜索群信息加群	不支持	不支持	不支持	不支持	不支持
是否支持申请加群	不支持	支持，但需要群主或管理员审批	支持，且无需审批	支持，且无需审批	支持，且无需审批
是否支持成员邀请他人加群	支持	不支持	不支持	不支持	支持

说明：

• 精确搜索：非群成员通过群组 ID 查找群组；模糊搜索：非群成员通过群名称等字段查找群组。
• 入群审批：群主和管理员可以针对群外用户的加群申请选择“同意”或“拒绝”，通过审批的用户方能加入群组。
• 不支持邀请加群的群类型，可以在 App 中通过群内成员分享群 ID 给他人申请加群达到类似效果。

成员管理能力差异

功能项	好友工作群（Work）	陌生人社交群（Public）	临时会议群（Meeting）	直播群（AVChatRoom）	社群（Community）
是否支持设置管理员	不支持	支持	支持	不支持	支持
是否支持群主退群	支持，退群后进入无群主状态	不支持	不支持	不支持	不支持
是否支持“踢人”	支持，群主可踢人	支持，群主和管理员有“踢人”权限，但管理员仅支持踢普通群成员	支持，群主和管理员有“踢人”权限，但管理员仅支持踢普通群成员	不支持，可用“禁言”功能达到类似效果	支持，群主和管理员有“踢人”权限，但管理员仅支持踢普通群成员
是否支持“禁言”	不支持	支持，群主和管理员有“禁言”权限，但管理员仅支持禁言普通群成员	支持，群主和管理员有“禁言”权限，但管理员仅支持禁言普通群成员	支持，群主有“禁言”权限	支持，群主和管理员有“禁言”权限，但管理员仅支持禁言普通群成员
定期移除不在线的群成员	支持，但默认不开启	支持，但默认不开启	支持，但默认不开启	不支持	不支持

注意：

被禁言的群成员，在禁言时间内无法发送群聊消息。

群组限制差异

功能项	好友工作群（Work）/陌生人社交群（Public）/临时会议群（Meeting）	直播群（AVChatRoom）	社群（Community）
成员数量上限	体验版：20人/群 专业版：默认为200人/群，最高支持 增值 扩展至2000人/群 旗舰版：默认为2000人/群，最高支持 增值 扩展至6000人/群	无上限	体验版：不支持 专业版：不支持 旗舰版：默认为10万人/群
群组数量	体验版：群组总数量不超过100个，已解散的群组不计数 专业版或旗舰版：无上限	体验版：最多同时存在10个，已解散的群组不计数 专业版：最多同时存在50个，已解散的群组不计数，支持 增值 扩展直播群创建数至无上限 旗舰版：无上限	体验版：不支持 专业版：不支持 旗舰版：默认可创建100000个

注意：

• 专业版或旗舰版 SDKAppID 下，所有群类型日净增群组数（即创建群组数减去解散群组数）上限为1万个。
• 专业版或旗舰版 SDKAppID 下，免费峰值群组数为10万个/月，超出免费量将产生 套餐外超量费用，建议及时解散无需继续使用的群组。

消息能力差异

功能项	好友工作群（Work）	陌生人社交群（Public）	临时会议群（Meeting）	直播群（AVChatRoom）	社群（Community）
是否支持未读消息计数	支持	支持	不支持	不支持	支持
是否支持历史消息存储	支持	支持	支持	不支持	支持
是否支持查看入群前漫游消息	默认关闭查看入群前漫游消息，支持 控制台 配置	默认关闭查看入群前漫游消息，支持 控制台 配置	默认开启查看入群前漫游消息，支持 控制台 配置	不支持	默认关闭查看入群前漫游消息，支持 控制台 配置
群成员变更通知	邀请进群，申请进群，踢人，退群默认下发通知且存漫游，支持 控制台 配置	邀请进群，申请进群，踢人，退群默认下发通知且存漫游，支持 控制台 配置	邀请进群，申请进群，踢人，退群默认关闭通知，支持 控制台 配置	邀请进群，申请进群，踢人，退群下发通知且不存漫游	邀请进群，申请进群，踢人，退群默认下发通知且存漫游，支持 控制台 配置
群资料变更通知	群名称，群通知，群简介，群头像，群主变更默认下发通知且存漫游，群禁言，申请加群方式变更默认关闭通知，支持 控制台 配置	群名称，群通知，群简介，群头像，群主变更默认下发通知且存漫游，群禁言，申请加群方式变更默认关闭通知，支持 控制台 配置	群名称，群通知，群简介，群头像，群主变更默认下发通知且存漫游，群禁言，申请加群方式变更默认关闭通知，支持 控制台 配置	群名称，群通知，群简介，群头像，群主变更下发通知且不存漫游，群禁言，申请加群方式变更关闭通知	群名称，群通知，群简介，群头像，群主变更默认下发通知且存漫游，群禁言变更默认关闭通知，支持 控制台 配置。社群申请加群方式不支持修改，因此无通知
群成员资料变更通知	群成员禁言，群管理员变更默认下发通知且存漫游，支持 控制台 配置	群成员禁言，群管理员变更默认下发通知且存漫游，支持 控制台 配置	群成员禁言，群管理员变更默认关闭通知，支持 控制台 配置	群成员禁言，群管理员变更默认关闭通知，支持 控制台 配置	群成员禁言，群管理员变更默认下发通知且存漫游，支持 控制台 配置
创建群组后是否需要发一条消息激活	需要	不需要	不需要	不需要	不需要
默认消息接收选项	接收在线推送消息和离线推送	接收在线推送消息和离线推送	只接收在线推送消息	只接收在线推送消息	接收在线推送消息和离线推送

注意：

• 需要激活的群组，在群主发消息前为未激活状态，对群主以外的其他群成员不可见，而不需要激活的群组，创建后即对所有群成员可见。
• 离线推送目前只支持 Android（Android 离线推送）和 iOS（APNs 推送）。
• 好友工作群（Work）、陌生人社交群（Public）、临时会议群（Meeting）和社群（Community）具备历史消息存储能力，默认免费存储7天（旗舰版默认30天），如需保存更长时间，您可以在 控制台 修改消息存储时长。延长历史消息存储时长是付费增值服务，详情请参见 价格说明。

批量导入与自动回收差异

功能项	好友工作群（Work）/ 陌生人社交群（Public）/ 临时会议群（Meeting）/社群（Community）	直播群（AVChatRoom）
允许导入群、群成员和群消息	允许导入群、群成员和群消息，适用于从第三方平台迁移历史群组到即时通信 IM 时使用	不允许批量导入群、群成员和群消息，只能使用现有的群、群成员和群消息
群组自动回收时间（秒）	后台不会回收群组，除非群主解散群，或者所有成员都退出群组（关于解散群组：后台不会主动解散群，除非群主解散，或者配置自动回收后，会不定期遍历群，如果发现该群经过 n 秒没有人说话或者被修改群资料，则进行解散。）	后台不会回收群组，除非群主解散，或者所有成员都退出群组

注意：

如果需要开启群组回收功能，可以根据 [工单模板](配置变更需求工单 | 腾讯云 (tencentcloud.com)#.E8.87.AA.E5.8A.A8.E5.9B.9E.E6.94.B6.E7.BE.A4.E7.BB.84) 提交工单进行申请。配置后，将会根据群组类型清理不活跃群组（群组不活跃是指群组中既没人发言，也没有成员变更）。

群组数据结构介绍

群基础资料

字段名称	类型	描述	备注
GroupId	String	群组的唯一标识	只读 群组 ID，App 内保证唯一，其格式前缀为 @TGS#。另外，App 亦可自定义群组 ID
Type	String	群组类型	只读 默认支持以下群组类型：好友工作群（Work）、陌生人社交群（Public）、临时会议群（Meeting）、直播群（AVChatRoom）、社群（Community），详情请参阅 群组类型介绍 旧版本 SDK 中还包含 Private、ChatRoom 以及 BChatRoom 类型，不建议使用
Name	String	群组名称	可读可写。最长30字节，不可调整
Introduction	String	群组简介	可读可写。最长240字节，不可调整
Notification	String	群组公告	可读可写。最长300字节，不可调整
FaceUrl	String	群组头像 URL	可读可写。最长100字节，不可调整
Owner_Account	String	群主 ID	只读
CreateTime	Integer	群组的创建时间	只读
InfoSeq	Integer	群资料的每次变都会增加该值	只读
LastInfoTime	Integer	群组最后一次信息变更时间	只读
LastMsgTime	Integer	群组内最后发消息的时间	只读
NextMsgSeq	Integer	群内下一条消息的 Seq	只读 群组内每一条消息都有一条唯一的消息 Seq，且该 Seq 是按照发消息顺序而连续的。从1开始，群内每增加一条消息，NextMsgSeq 就会增加1（默认情况下系统消息比如进退群等通知也属于消息，会导致 NextMsgSeq 加1）
MemberNum	Integer	当前成员数量	只读
MaxMemberNum	Integer	最大成员数量	缺省时的默认值：付费上限，例如体验版是20，如果升级，需按照修改群基础资料修改这个字段到对应数值
ApplyJoinOption	String	申请加群选项	申请加群选项包括如下几种： DisableApply 表示禁止任何人申请加入 NeedPermission 表示需要群主或管理员审批 FreeAccess 表示允许无需审批自由加入群组

注意：

群组名称、群组简介、群组公告和群组头像 URL 字段的修改权限如下：

• 好友工作群（Work）中，任何群成员都可以修改.
• 其他群组类型则需要非普通成员角色才可修改。

群成员资料

字段名称	类型	描述	备注
Member_Account	String	群成员 ID	只读
Role	String	群内身份	群内身份，包括 Owner 群主、Admin 群管理员以及 Member 群成员
JoinTime	Integer	入群时间	只读
MsgSeq	Integer	该成员当前已读消息 Seq	只读
MsgFlag	String	消息接收选项	消息接收选项，包括如下几种： AcceptAndNotify 表示接收并提示 AcceptNotNotify 表示接收不提示（不会触发 APNs 远程推送） Discard 表示屏蔽群消息（不会向客户端推送消息）
LastSendMsgTime	Integer	最后发送消息的时间	支持三个普通群，不支持直播群
NameCard	String	群名片	可读可写。最长50字节，不可调整
MuteUntil	Integer	禁言状态	0表示未被禁言，否则为禁言的截止时间戳

自定义群组 ID

默认情况下，App 创建群时，即时通信 IM 会为新创建的群组分配一个默认的群组 ID。该 ID 将以 @TGS# 开头，且保证在 App 中唯一。
为了使得群组 ID 更加简单，便于记忆传播，即时通信 IM 支持 App 在通过 REST API 创建群组时自定义群组 ID。自定义群组 ID 必须为可打印 ASCII 字符（0x20-0x7e），最长48个字节，且前缀不能为 @TGS#（避免与默认分配的群组 ID 混淆）。

注意：

社群（Community）前缀必须是@TGS#_。

自定义话题 ID

默认情况下，App 创建话题时，即时通信 IM 会为新创建的话题分配一个默认的话题 ID。该 ID 将以 GroupId+@TOPIC#_开头，且保证在群组内唯一。

为了使得话题 ID 更加简单，便于记忆传播，即时通信 IM 支持 App 在通过 REST API 创建话题时自定义话题 ID。自定义话题 ID 的形式为GroupId+@TOPIC#_+自定义部分，其中自定义部分不能包括@TGS#_和@TOPIC#_@TOPIC# （避免与默认分配的群组 ID 混淆）, 且必须为可打印 ASCII 字符（0x20-0x7e）。

例如 GroupId 为 @TGS#_@TGS#cQVLVHIM62CJ，自定义部分为 TestTopic，则最终的自定义话题 ID 为 @TGS#_@TGS#cQVLVHIM62CJ@TOPIC#_TestTopic。整个自定义话题 ID 长度需要保证在96个字节内。

自定义字段

即时通信 IM 支持 App 根据业务需求，在群组和群成员两个维度上设置自定义字段。群组维度最多支持10个字段，群成员维度最多支持5个字段。利用自定义字段，App 可以将一些额外数据附加到群组之上，并可以通过现有接口进行读写操作。

特性介绍

每个自定义字段有以下特性：

• 为 Key-Value 形式。
• Key 为 String 类型，长度不超过16字节，其命名仅支持英文大小写字母、数字、下划线。
• Value 为用户自定义 Buffer，可以为二进制数据，群维度的 Value 长度不超过512字节，群成员维度的 Value 长度不超过64字节。
• 支持配置每个 Key 的最小读权限、最小写权限。

每个自定义字段的读写权限从高到低分别为：

1. App 管理员可读/可写。
2. 群主可读/可写。
3. 群管理员可读/可写。
4. 群成员可读/可写。
5. 任何人（包括非成员）可读/可写。

例如，App 需要在群组中扩展一个字段 GroupLevel，其 Value 为一个数字，用于记录该群的等级信息。假设等级信息需要 App 后台计算得出，那么该字段的最小写权限应当为“App 管理员可写”。该字段应当为群的公开资料，故而其最小读权限应当为“任何人（包括非成员）可读”。

对于 C/C++ 开发者，如果需要存储的 Value 是数字，建议将其存储为数字的字符串形式，而非其二进制形式（例如，当存储的数字是1时，建议存储字符串“1”，而非二进制数据 0x01）。对于自定义字段，即时通信 IM 后续会扩展出更多操作方式，例如对 Value 进行特定数学操作等，这些运算未来都会以基于字符串形式表示的数字来进行操作。

配置方法

这两个维度的自定义字段，都可以通过即时通信 IM 控制台进行配置。
配置群成员维度的自定义字段前，需要先指定群组类型。但对于直播群（AVChatRoom）及以其为参考的群组类型，因为不存储所有群成员的资料，所以不支持群成员维度的自定义字段。
“自己的读写权限”是指对于用户本人的群成员维度自定义字段值，自己是否有读写权限。例如，群成员维度的自定义字段 “MemberLevel”，用于表示成员在群组中的等级，本人可以读取自己的等级，但无权修改自己的等级，因此字段的“自己的读写权限”为“可读/不可写”。

注意：

不支持删除或者修改已配置的自定义字段，请谨慎操作。

自定义回调

第三方回调是 App 实现特殊需求的重要方式之一，为用户提供了自定义行为的能力。
即时通信 IM 群组系统支持多种回调，具体参见 第三方回调简介以及 回调命令列表。