- 动态与公告
- 产品简介
- 购买指南
- 开发指引
- Demo 专区
- 下载中心
- 聊天互动（含 UI）
- 视频通话（含 UI）
- 推送功能
- 智能客服
- 更多实践
- 无 UI 集成
- 客户端 API
- 服务端 API
- 控制台指南
- 常见问题
- 协议与认证
- IM 政策
- 平滑迁移方案
- 错误码
- 联系我们
- 动态与公告
- 产品简介
- 购买指南
- 开发指引
- Demo 专区
- 下载中心
- 聊天互动（含 UI）
- 视频通话（含 UI）
- 推送功能
- 智能客服
- 更多实践
- 无 UI 集成
- 客户端 API
- 服务端 API
- 控制台指南
- 常见问题
- 协议与认证
- IM 政策
- 平滑迁移方案
- 错误码
- 联系我们
群组系统简介
群组系统是一个支持多人聊天的即时通信系统，群组系统所具备的基本能力包括：
完备的 群组管理 能力：创建/解散群组、成员管理、群组资料管理、成员资料管理等。
稳定可靠的消息收发能力，完善的 群组消息 管理机制：权限控制，禁言，消息回调，消息漫游等。
根据常见使用场景，默认配置了好友工作群（Work）、陌生人社交群（Public）、临时会议群（Meeting）、直播群（AVChatRoom）和社群（Community） 五个群组类型。
可拓展的群成员人数上限：
好友工作群（Work）、陌生人社交群（Public）和临时会议群（Meeting）成员人数上限最高支持付费拓展到6000人，详情请参阅 价格说明。
社群（Community）最高支持10万人。
直播群（AVChatRoom）成员人数无上限。
注意
直播群（AVChatRoom）不设成员人数上限，但如果预期群成员会出现短时间内激增的场景（例如举行大型在线活动，单群成员人数达到5万或以上等情况），请提前联系 腾讯云客服 或商务工作人员，提供 SDKAppID 和活动预期发生时间进行服务资源报备。
目前仅非直播群具备历史消息存储能力（开发版及标准版默认7天，进阶版默认30天）。如需保存更长时间，您可以在 控制台 修改消息历史消息存储时长。延长历史消息存储时长是付费增值服务，具体计费说明请参考 价格说明。
社群（Community），娱乐协作新利器。同一社群内，既可划分不同分组、话题，将消息相互区隔，进行分层级沟通；又可容纳超大规模成员，共用一套好友关系，助您摸索出一条独特的社交扩张路径；适用于兴趣交友、游戏社交、粉丝运营、组织管理等场景。
除此之外，即时通信 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） | 直播群（AVChatRoom） |
允许导入群、群成员和群消息 | 允许导入群、群成员和群消息，适用于从第三方平台迁移历史群组到即时通信 IM 时使用 | 不允许批量导入群、群成员和群消息，只能使用现有的群、群成员和群消息 |
群组自动回收时间（秒） | 后台不会回收群组，除非群主解散群，或者所有成员都退出群组（关于解散群组：后台不会主动解散群，除非群主解散，或者配置自动回收后，会不定期遍历群，如果发现该群经过 n 秒没有人说话或者被修改群资料，则进行解散。） | 后台不会回收群组，除非群主解散，或者所有成员都退出群组 |
注意
群组数据结构介绍
群基础资料
字段名称 | 类型 | 描述 | 备注 |
GroupId | String | 群组的唯一标识 | 只读 群组 ID，App 内保证唯一，其格式前缀为 @TGS#。另外，App 亦可自定义群组 ID |
Type | String | 群组类型 | 只读 旧版本 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 表示接收不提示（不会触发离线推送） Discard 表示屏蔽群消息（不会向客户端推送消息） AcceptNotNotifyExceptAt 表示接收并提示 at 消息（仅 at 消息触发离线推送，其他消息不触发） |
LastSendMsgTime | Integer | 最后发送消息的时间 | |
NameCard | String | 群名片 | 可读可写。最长50字节，不可调整 |
MuteUntil | Integer | 禁言状态 | 0表示未被禁言，否则为禁言的截止时间戳 |
权限组资料
字段名称 | 类型 | 描述 | 备注 |
PermissionGroupId | String | 权限组的唯一标识 | 只读 |
PermissionGroupName | String | 权限组名称 | 可读可写，最长150字节，不可调整 |
Permission | Integer | 权限组的权限 | 可读可写，64位整数，每一位代表一个管理权限 |
CustomString | String | 权限组的自定义字段 | 可读可写，最长3000字节，业务层可以使用此字段来实现特殊场景的需求 |
MemberNum | Integer | 权限组中的成员数量 | 只读 |
CreateTime | Integer | 权限组的创建时间 | 只读 |
权限组中权限介绍
对群组中的权限管理主要通过权限组资料中的权限和针对话题的权限来完成。其中每一位代表一个权限，当设置某个权限位为1时，代表具有此项管理权限。
权限组中的权限含义介绍
权限名称 | 描述 | 权限位及其值 |
ManageGroupInfo | 修改群资料权限 | 1<<0（左移0位，下同） |
ManageGroupMember | 群成员进出管理和修改群成员资料权限 | 1<<1 |
ManagePermissionGroupInfo | 1. 创建、修改、删除权限组权限； 2. 在所有话题中设置权限组（添加、修改、删除）权限 | 1<<2 |
ManagePermissionGroupMember | 权限组成员进出管理权限 | 1<<3 |
ManageTopic | 创建、修改、删除话题权限 | 1<<4 |
GroupMuteMember | 禁言群成员权限 | 1<<5 |
SendGroupMessage | 在社群中发消息权限 | 1<<6 |
GroupAtAll | 在社群中发消息时支持@all的权限 | 1<<7 |
GetGroupHistoryMessage |
拉取入群前的历史消息权限 | 1<<8 |
RevokeOtherMemberGroupMessage | 撤回他人群消息权限 | 1<<9 |
BanMemberGroupMessage | 封禁群成员的权限 | 1<<10 |
针对话题的权限介绍
权限名称 | 描述 | 权限位及其值 |
ManageTopicInfo | 修改、删除话题权限 | 1<<0（左移0位，下同） |
ManagePermissionTopicInfo | 在该话题中设置权限组（添加、修改、删除）权限 | 1<<1 |
TopicMuteMember | 在话题中禁言成员权限 | 1<<2 |
SendTopicMessage | 在话题中发消息权限 | 1<<3 |
GetTopicHistoryMessage | 拉取入群前的话题历史消息权限 | 1<<4 |
RevokeOtherMemberTopicMessage | 撤回他人话题消息权限 | 1<<5 |
TopicAtAll | 在话题中发消息时支持@all 的 权限 | 1<<6 |
自定义群组 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个字节内。自定义权限组 ID
默认情况下，App 创建权限组时，即时通信 IM 会为新创建的权限组分配一个默认的权限组ID。该 ID 将以 @PMG#_@PMG#开头，且保证在群组内唯一。
为了使得权限组 ID 更加简单，便于记忆传播，即时通信 IM 支持 App 在通过 REST API 创建权限组时自定义权限组 ID。自定义权限组 ID 必须以@PMG#_开头（但是不能以@PMG#_@PMG#开头，避免与默认分配的权限组ID混淆）且为可打印 ASCII 字符（
0x20-0x7e）。自定义字段
即时通信 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”，用于表示成员在群组中的等级，本人可以读取自己的等级，但无权修改自己的等级，因此字段的“自己的读写权限”为“可读/不可写”。
注意
不支持删除或者修改已配置的自定义字段，请谨慎操作。
是
否
本页内容是否解决了您的问题？