常规集成(无 UI 库)

服务端 API

群组系统

最近更新时间:2020-07-07 15:13:26

群组系统简介

群组系统是一个支持多人聊天的即时通信系统,以下视频为您详细介绍群组系统:

群组系统所具备的基本能力包括:

  • 完备的 群组管理 能力:创建/解散群组、成员管理、群组资料管理、成员资料管理等。
  • 稳定可靠的消息收发能力,完善的 群组消息 管理机制:权限控制,禁言,脏词过滤,消息回调,消息漫游等。
  • 根据常见使用场景,默认配置了好友工作群(Work)陌生人社交群(Public)临时会议群(Meeting)直播群(AVChatRoom) 四个群组类型,并支持业务根据自身需要 自定义群组类型
  • 可拓展的群成员人数上限:
    • 非直播群成员人数上限最高支持付费拓展到6000人,详情请参阅 价格说明
    • 直播群(AVChatRoom)成员人数无上限。
  • 在 Web/小程序 端,直播群(AVChatRoom)支持用户以游客身份(即不需要登录)接收消息。
注意:

  • 直播群(AVChatRoom)不设成员人数上限,但如果预期群成员会出现短时间内激增的场景(例如举行大型在线活动,单群成员人数达到5万或以上等情况),请提前联系 腾讯云客服 或商务工作人员,提供 SDKAppID 和活动预期发生时间进行服务资源报备。
  • 目前仅非直播群具备历史消息存储能力(体验版及专业版套餐包默认7天,旗舰版默认30天)。如需保存更长时间,您可以在 控制台 修改消息历史消息存储时长。延长历史消息存储时长是付费增值服务,具体计费说明请参考 价格说明

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

群成员角色介绍

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

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

群组类型介绍

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

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

群组基础能力操作差异

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

  • 对于好友工作群(Work),普通成员只能修改群名称、简介、公告、群头像 URL,不能修改其他群基础资料。
  • 如果群类型中的角色不能满足业务需求,可以通过设置群成员 自定义字段 来增加新角色。
  • 获取部分群成员的信息,常用于直播群(AVChatRoom)中只需要展示部分群成员列表的场景。

加群方式差异

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

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

成员管理能力差异

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

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

群组限制差异

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

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

消息能力差异

功能项 好友工作群(Work) 陌生人社交群(Public) 临时会议群(Meeting) 直播群(AVChatRoom)
是否支持未读消息计数 支持 支持 不支持 不支持
是否支持查看入群前消息记录 不支持 不支持 支持 不支持
是否支持历史消息存储 支持 支持 支持 不支持
是否支持成员变更通知 支持 支持 不支持 支持
创建群组后是否需要发一条消息激活 需要 不需要 不需要 不需要
默认消息接收选项 接收在线推送消息和离线推送 接收在线推送消息和离线推送 只接收在线推送消息 只接收在线推送消息
是否支持用户以游客身份(即不需要登录)接收群消息 不支持 不支持 不支持 支持
注意:

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

批量导入与自动回收差异

功能项 好友工作群(Work)/ 陌生人社交群(Public)/ 临时会议群(Meeting) 直播群(AVChatRoom)
允许导入群、群成员和群消息 允许导入群、群成员和群消息,适用于从第三方平台迁移历史群组到即时通信 IM 时使用 不允许批量导入群、群成员和群消息,只能使用现有的群、群成员和群消息
群组自动回收时间(秒) 后台不会回收群组,除非群主解散,或者所有成员都退出群组 后台不会回收群组,除非群主解散,或者所有成员都退出群组
注意:

如果需要开启群组回收功能,可以根据 工单模板 提交工单进行申请。配置后,将会根据群组类型清理不活跃群组(群组不活跃是指群组中既没人发言,也没有成员变更)。

群组数据结构介绍

群基础资料

字段名称 类型 描述 备注
GroupId String 群组的唯一标识 只读
群组 ID,App 内保证唯一,其格式前缀为 @TGS#。另外,App 亦可自定义群组 ID
Type String 群组类型 只读
默认支持以下群组类型:好友工作群(Work)、陌生人社交群(Public)、临时会议群(Meeting)、直播群(AVChatRoom),详情请参阅 群组类型介绍
旧版本 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
MemberNum Integer 当前成员数量 只读
MaxMemberNum Integer 最大成员数量 -
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 群名片 可读可写

自定义群组类型

在实际使用中,如果 IM 提供的 群组类型 无法满足您的需求,您可以按照 工单模板 准备相关信息,然后 提交工单 申请修改现有群组类型或新增自定义群组类型。
例如,某种办公场景下使用的群组,它与好友工作群(Work)相似但需要群内任意成员都具有最高级别的管理权限且可以查看入群之前的历史消息。那么您可以选择以下方案:

  • 选择使用好友工作群(Work), 然后 提交工单 申请开启“是否支持查看入群前历史消息”和“是否允许普通成员踢人”选项。
  • 提交工单 申请定义一种新的群组类型:OAGroup,指定好友工作群(Work)为参考类型,并开启“是否支持查看入群前历史消息”和“是否允许普通成员踢人”选项。
注意:

  • 新增群组类型时,需要指定一种群组类型作为参考类型。其中,旧 SDK 版本中的 BChatRoom 类型不能作为参考类型。
  • 成功配置后,除了在申请工单中指定要修改的特性外,新群组类型具有的特性与参考类型是相同的。

自定义群组 ID

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

自定义字段

即时通信 IM 支持 App 根据业务需求,在群组和群成员两个维度上设置自定义字段。群组维度最多支持20个字段,群成员维度最多支持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 群组系统支持多种回调,具体参见 第三方回调简介以及 回调命令列表

目录