超级群会话类型
rev22 起，契约新增会话类型 SUPER_GROUP（数值 10），用于显式表达超级群会话。此前超级群用“普通群类型 GROUP(2) + 群属性 groupType=super”表达：客户端、回调与统计都要先读群对象才能判断。本页说明 10 的语义、与普通群的区别、发送/历史/会话列表规则、频道与用户组、存量兼容与限制。
契约：IDL v1.0.0 / 修订 35。新增取值不改变既有 1/2/3/4 语义。
存量：GROUP(2) + groupType=super 的会话与消息继续可读；新消息使用 SUPER_GROUP(10)。
会话键按 groupId 聚合：2 与 10 指向同一个群会话（g:{groupId}），不会因为类型不同产生两条会话或两份历史。
取值与语义
| ConversationType | 值 | targetId 语义 | 持久化 / 补发 | 说明 |
|---|---|---|---|---|
| PRIVATE | 1 | 对方 userId | 持久化、离线补发 | 单聊 |
| GROUP | 2 | groupId | 持久化、离线补发 | 普通群；存量超级群也用 2 + groupType=super 表达 |
| CHATROOM | 3 | chatroomId | 不持久化、不补发 | 在线态会话 |
| SYSTEM | 4 | system（固定） | 按用户隔离持久化 | 系统通知 |
| SUPER_GROUP | 10 | groupId | 持久化、离线补发 | rev22 新增：显式超级群会话类型 |
协议语义（protocol.json superGroupSemantics）：conversationType=SUPER_GROUP(10)；存量 GROUP(2) + groupType=super 仍可读，新消息写 10。超级群成员上限 100000（普通群 3000），加入策略 invite|open（由群属性决定，默认 invite）。
为什么新增 10
| 维度 | 2 + groupType=super（存量） | SUPER_GROUP(10)（rev22） |
|---|---|---|
| 会话类型自描述 | 否：会话/消息类型都是 2，需再查群属性 | 是：10 本身即表示超级群 |
| 客户端渲染 | 先读 groupType 再决定群样式/入口 | 可直接按 10 选择超级群样式与入口 |
| 回调与统计 | 按 conversationType=2 归档后需 join 群表才能区分普通群/超级群 | 按 conversationType=10 即可区分（存量数据仍按 2+群属性归类） |
| 历史/消息 | 消息 conversationType=2 | 新消息 conversationType=10；同一会话历史里两种取值可能并存 |
| 兼容策略 | 继续可读，不需要改写存量数据 | 新消息写 10；旧客户端需按 2+groupType 兜底 |
发送、历史与会话列表
| 操作 | 传参 | 契约行为 | 注意事项 |
|---|---|---|---|
| 发送消息 | sendMessage(10, groupId, content) / sendTextMessage(10, groupId, text) | 按群语义校验成员、计算收件人、分配 seq、投递与离线补发 | 非群成员 1003/1006；消息体积与限频同普通消息；rev23 起可带 options.channelId 发频道消息 |
| 历史消息 | getHistoryMessages(10, groupId, {limit, beforeSeq}) | 读取该群会话的历史；传 2 或 10 都指向同一会话键 | 历史中的消息可能同时含 2 与 10（存量 + 新消息），按 seq 排序即可；rev23 起可加 channelId 过滤频道 |
| 会话列表 | getConversationList() | 返回该用户全部会话；超级群的会话类型可能是 10（新会话）或 2（存量会话） | 用 groupType === "super" 或 conversationType === 10 判断超级群；频道消息不单独成会话 |
| 未读/已读/撤回/扩展/回应/流式/typing/搜索/标签 | 与普通群相同 | 全部按群语义工作（不需要为 10 单独实现分支） | 客户端不要硬编码“等于 2 才是群”；频道消息的未读/回执按频道成员收窄（rev23） |
| 系统通知 | — | 超级群不产生独立的系统通知会话；群事件走系统通知与群事件回调 | — |
rev23 起超级群消息可带 channelId：仅频道成员接收、历史按频道过滤、私有频道需成员、公有频道群成员发送自动加入；不带 channelId 仍是群级消息。
会话视图对群类会话（2/10）返回 groupType: "normal"|"super"：10 恒为 super；2 按群属性判定（存量超级群仍返回 super）。
因此判断超级群的推荐顺序是：先看会话 groupType，再兜底看 conversationType === 10 或（2 且群 groupType=super）。
频道与用户组
超级群的频道（channel）与用户组（userGroup）是群内组织与可见性单元：频道保存类型（public/private）、成员与绑定关系；用户组用于批量把成员绑定到频道。客户端 SDK 提供 8 个语义操作，服务端另有 supergroup.channel.* / supergroup.usergroup.* Open API（同一份状态）。
| 操作 | 入参 | 返回 | 错误码 |
|---|---|---|---|
createSupergroupChannel | params:{groupId:string, name:string, type:ChannelType, joinPolicy?:JoinPolicy} | SupergroupChannel | 1001 1002 1003 1005 1015 |
listSupergroupChannels | groupId:string | {groupId:string, channels:SupergroupChannel[], total:uint32} | 1001 1002 1003 1005 |
joinSupergroupChannel | channelId:string, options:{groupId?:string}? | {groupId:string, channelId:string, userId:string, joined:bool, alreadyJoined:bool} | 1001 1002 1003 1005 |
leaveSupergroupChannel | channelId:string, options:{groupId?:string}? | {groupId:string, channelId:string, userId:string, left:bool, wasMember:bool} | 1001 1002 1003 1005 |
bindUserGroupToChannel | channelId:string, userGroupId:string, options:{groupId?:string}? | {groupId:string, channelId:string, userGroupId:string, bound:bool, reverseIndexed:bool} | 1001 1002 1003 1005 |
createUserGroup | params:{groupId:string, name:string, members?:string[]} | UserGroup | 1001 1002 1003 1004 1015 |
listUserGroups | groupId:string | {groupId:string, userGroups:UserGroup[], total:uint32} | 1001 1002 1003 1005 |
getUserGroupsByUser | userId:string, options:{groupId?:string}? | {userId:string, userGroups:UserGroup[], total:uint32} | 1001 1002 1003 |
| 规则 | 事实 |
|---|---|
| 频道类型与加入策略 | type=public → joinPolicy=open；type=private → joinPolicy=invite；显式传入矛盾值返回 1001 |
| 权限 | 创建频道 / 创建用户组 / 绑定用户组仅群主或管理员（1003）；频道列表与用户组列表仅群成员可读 |
| 配额 | 单群 100 个频道、100 个用户组（超限 1015）；频道/用户组数量与命名限制在接口内校验 |
| 绑定关系 | 绑定同时维护频道侧 userGroupIds 与用户组侧 channelIds（双向索引），可用 listUserGroups / getUserGroupsByUser 反查 |
| 消息隔离 | 已实现（rev23）：消息带 channelId 时按频道投递（仅频道成员接收、历史可过滤）；不带 channelId 为群级消息。私有频道发送需成员（1003），公有频道群成员可发并自动加入 |
| 默认频道 | 不自动创建 RCDefault 默认频道；频道必须显式创建 |
事件与回调
| 通道 | 字段 | 10 的取值/映射 |
|---|---|---|
| 客户端长连接事件 | MESSAGES / CONVERSATION 载荷中的 conversationType | 新消息为 10；存量消息为 2 |
| 服务端回调（22 类事件） | 载荷中的 conversationType（rev23 起频道消息另带 channelId） | 随消息/会话：10 或存量 2；回调载荷没有 channelType 字段，不要读取不存在的字段 |
| 机器人 / 集成回调 | channelType | PERSON=单聊、GROUP=普通群、ULTRAGROUP=超级群（10 与存量 2+super 都映射 ULTRAGROUP）、TEMP_GROUP=聊天室 |
| 控制台消息追踪 / 统计 | conversationType 数值与标签 | 2=群聊（含存量超级群）、10=超级群；控制台版本未升级时 10 可能显示原值 |
存量迁移（摘要）
- 客户端先做读兼容：判断超级群时同时接受
conversationType===10与conversationType===2 && groupType==="super"。 - 升级服务端与各端 SDK 到包含 rev22 的版本（服务端把 10 当群语义处理；SDK 提供 10 的常量与序列化）。
- 新消息写 10：发送时传
SUPER_GROUP；存量会话/消息保持原样，不做批量改写。 - 统计与回调按“10 或（2 且 groupType=super）”双口径汇总，避免迁移期数据断层。
- 灰度：按应用或按用户分批升级；回滚时旧版本客户端仍能读 2+super 的存量数据。
判断函数、双表示并存的展示口径、回调/控制台映射与常见问题见 超级群类型迁移与兼容 FAQ。
错误处理
| 错误码 | 名称 | 含义 | 可重试 |
|---|---|---|---|
1001 | INVALID_PARAMETER | 参数错误 | 否 |
1002 | INVALID_TOKEN | Token 无效或已过期 | 否 |
1003 | FORBIDDEN | 无权限 | 否 |
1005 | GROUP_NOT_FOUND | 群组不存在 | 否 |
1006 | NOT_GROUP_MEMBER | 未加入群组 | 否 |
1009 | GROUP_MUTED | 你已被禁言 | 否 |
1015 | MEMBERSHIP_LIMIT | 成员数量超出上限 | 否 |
1016 | USER_BANNED | 账号已被封禁 | 否 |
1021 | SERVICE_NOT_ACTIVATED | 服务未开通 | 否 |
若调用发送/历史返回 1001 invalid conversationType，说明该端 SDK 或服务端尚未升级到包含 rev22 的版本：此时继续用 GROUP(2) + groupType=super 兼容写法（见迁移 FAQ）。
限制
- 频道级消息已实现（rev23）：消息可带
channelId按频道投递/过滤；但typing未按频道收窄、客户端searchMessages未按频道裁剪、频道消息不单独成会话（未读/回执按群会话聚合）。 - IMKit 只提供单频道会话视图：10 的会话需 IMKit 升级到识别 rev22/rev23 的版本；频道列表/成员管理页需宿主实现。
- 默认频道与默认免打扰未实现：不自动创建默认频道，也不支持群/频道级默认免打扰（只能用会话级提醒级别）。
- iOS / HarmonyOS 为契约预留：声明同构，无运行时代码。
- 存量数据不改写：2+super 的历史会话与消息保持原样；若业务需要“全部 10”，只能在新消息上逐步生效或自行迁移展示层。