群组订阅方法
group.subscribe
group.subscribe 原子替换当前 WebSocket 连接的群订阅集合。成功订阅后，连接可以接收相应的群组通知。
| 项目 | 约定 |
|---|---|
| HTTP | 不支持 |
| 会话要求 | 设备会话 |
| WSS | group.subscribe |
请求参数
| 字段 | 类型 | 必需 | 语义与约束 |
|---|---|---|---|
group_ids |
array<string> | 是 | 这条 WebSocket 连接在调用成功后应订阅的完整群 ID 集合；数组可以为空，表示取消当前连接的全部群订阅；每个群都必须由当前中继托管且当前账户有读取权，ID 不得重复，数量按下文的订阅上限规则检查 |
响应对象
无。
处理与错误
参数与会话校验
中继必须验证请求参数和设备会话。数组包含重复或非法群 ID，或者不满足下述数量规则时返回 bad_request；会话无效时返回 unauthorized；会话模式不符合要求时返回 forbidden。存在上述错误时，从实际发生的错误中选择一个返回，并省略 error.data。
数量检查以本次替换生效前、当前连接仍有效的群订阅集合为基准。请求包含任一尚未订阅的群时，完整新集合的数量不得超过 relay.info.limits.max_group_subscriptions 的当前值；没有新增群订阅时，不得仅因数量仍超过当前上限而拒绝。数组顺序不影响集合比较。取消后重新加入的群属于新增订阅。
群归属与访问权限校验
中继还必须检查请求中每个群的归属和访问权限。群不存在、不由当前中继托管，或者调用账户不是当前成员或已被封禁时，该群不能订阅。请求参数及设备会话均有效时，任一群不能订阅就拒绝整个请求，并按下表返回错误：
| 情况 | 错误码 |
|---|---|
| 至少一个群不存在或不由当前中继托管 | not_found |
| 所有群均存在且由当前中继托管，但至少一个群不允许当前账户或设备访问 | forbidden |
这两类群校验错误必须在 JSON-RPC 错误对象的 data 中提供：
| 字段 | 类型 | 必需 | 语义与约束 |
|---|---|---|---|
group_ids |
array<string> | 是 | 本次请求中不能订阅的全部群 ID，包括归属与访问权限两类原因；非空、不重复，每项均来自请求的 group_ids |
调用失败时，原订阅集合和所有群的设备访问区间均保持不变。
订阅生效与同步
全部群均可订阅时，中继以请求中的集合完整替换这条 WebSocket 连接原有的群订阅，并按设备访问区间的规定建立所需区间。取消订阅不结束设备访问区间，也不改变群成员资格、状态、事件或密钥版本。重复提交相同集合成功时，保持该订阅集合和仍有效的访问起点；需要新区间时仍按上述规则建立。
订阅成功不主动返回当前状态或积压通知。建议客户端在成功订阅后对本次新增订阅的群调用 group.sync，补齐订阅生效前可能遗漏的事件；同一连接上持续有效且本次继续保留的订阅，不要求仅因集合调整或重复提交而额外同步。本地已完成位置不因断线或重新订阅而重置。
通知、已知历史缺口及其他状态恢复原因触发的事件补同步要求继续适用，持续订阅不免除这些要求。密钥材料按需通过 group.key.sync 补齐；本地已具备所需版本且通过原验证规则的材料可以复用。