超级群私有频道操作指南

私有频道用于“只让指定成员看到/参与”的分区：创建时 type=private（默认），通过频道成员或用户组绑定授权。rev23 起服务端按频道消息路由强制鉴权：私有频道发送者必须是频道成员（否则 1003），收件人仅频道成员；非成员在群历史中也看不到该频道消息。

概念​

动作接口语义
创建私有频道channel/create，type 省略或 private默认私有
加/移成员channel/members/add|remove维护频道成员（决定发送权与接收范围）
查成员channel/members/list返回频道成员
转公开channel/type/set，type=public转公开后群成员可发送并自动加入，历史对群成员可读
用户组授权channel/usergroup/bind用户组成员计入频道有效成员（需仍是群成员）
  • 频道成员/用户组绑定参与频道消息鉴权（rev23）：私有频道发送/读取要求频道成员，非成员 1003。
  • 列表可见性（rev24）：private 频道只对频道有效成员或群主/管理员出现在频道列表；群内其他人看不到该频道。
  • 私有频道没有密码、邀请链接或审批流；授权就是成员列表 + 用户组绑定。
  • 频道有效成员 = 显式成员 ∪ 绑定用户组成员，且必须仍是群成员（被移出群后失去接收资格）。
鉴权边界

rev23 起服务端强制：私有频道发送要求频道成员（1003），接收/历史按频道成员收窄（群内非成员不会收到该频道消息）。rev24 进一步把 private 频道从非成员的频道列表中隐藏（Open API 需传 userId 才按该用户过滤；匿名只返回 public）。

仍有未覆盖项：客户端 searchMessages 未按频道裁剪（Open API 搜索已过滤）、typing 未按频道收窄；不要把搜索当作私有频道隔离手段。频道成员管理页也需宿主实现。

前置条件​

  • 服务端已启动，Open API 基址 http://127.0.0.1:8080/im/v2。
  • 应用已创建并持有 appkey / appSecret；Open API 需要 App-Key + Nonce + Timestamp + Signature。
  • 已创建 groupType=super 的超级群；未开通 supergroup 服务时相关接口返回 1021。
  • 自托管版无购买/计费/套餐流程；频道与用户组不单独收费（不适用项）。
  • 已创建 super 群；已规划频道与用户组的授权关系。

步骤​

  1. 创建私有频道
    POST /supergroup/channel/create，type 省略（默认 private）或显式传 private。
  2. 确认列表可见性

    调用 supergroup/channel/list：客户端 REST 按当前用户过滤 private 频道；Open API 传 userId 按该用户过滤（缺省匿名只返回 public）。详见「私有频道列表可见性」。

  3. 添加频道成员
    POST /supergroup/channel/members/add，传 userIds 数组；成员必须是已注册用户。
  4. 查询与校验成员
    channel/members/list 返回成员；业务在发送前用它判断当前用户是否有权。
  5. 按用户组批量授权（可选）

    创建用户组并绑定频道：channel/usergroup/bind。适合“部门/角色”批量授权，见「用户组操作指南」。

  6. 切换公开/私有
    channel/type/set 在 private/public 间切换；切换不会清空成员列表，但公开后成员限制不再有意义。
  7. 配额校验与错误码

    单群频道数 ≤50、单频道绑定用户组 ≤10（产品口径）；服务端未强制，业务侧在创建/绑定前统计。

    错误码：1001 参数非法、1004 用户或群不存在（supergroup 实现）、1003 无权限、1021 服务未开通。

参数表​

操作方法与路径请求体
创建私有频道POST /im/v2/supergroup/channel/create{groupId,channelId,name?,type:"private"}
添加成员POST /im/v2/supergroup/channel/members/add{groupId,channelId,userIds[]}
移除成员POST /im/v2/supergroup/channel/members/remove{groupId,channelId,userIds[]}
成员列表POST /im/v2/supergroup/channel/members/list{groupId,channelId}
切换类型POST /im/v2/supergroup/channel/type/set{groupId,channelId,type}
绑定用户组POST /im/v2/supergroup/channel/usergroup/bind{groupId,channelId,userGroupId}
查绑定POST /im/v2/supergroup/channel/usergroup/list{groupId,channelId?} 或 {groupId,userGroupId?}

示例​

准备签名变量（所有示例共用）​

Shell
# 生成签名（Open API：hex(sha1(appSecret + nonce + timestamp))）
export APP_SECRET='<appSecret>'
export NONCE="$(node -e "console.log(Math.random().toString(36).slice(2,10))")"
export TS="$(node -e "console.log(Date.now())")"
export SIG="$(node -e "const c=require('crypto');console.log(c.createHash('sha1').update(process.env.APP_SECRET+process.env.NONCE+process.env.TS).digest('hex'))")"

创建私有频道 → 加成员 → 查成员​

Shell
curl -sS -X POST "http://127.0.0.1:8080/im/v2/supergroup/channel/create" \
  -H 'App-Key: demo' \
  -H "Nonce: $NONCE" \
  -H "Timestamp: $TS" \
  -H "Signature: $SIG" \ \
  -H 'content-type: application/json' \
  -d '{"groupId":"sg_demo","channelId":"vip","name":"VIP 频道","type":"private"}'

curl -sS -X POST "http://127.0.0.1:8080/im/v2/supergroup/channel/members/add" \
  -H 'App-Key: demo' \
  -H "Nonce: $NONCE" \
  -H "Timestamp: $TS" \
  -H "Signature: $SIG" \ \
  -H 'content-type: application/json' \
  -d '{"groupId":"sg_demo","channelId":"vip","userIds":["alice","bob"]}'

curl -sS -X POST "http://127.0.0.1:8080/im/v2/supergroup/channel/members/list" \
  -H 'App-Key: demo' \
  -H "Nonce: $NONCE" \
  -H "Timestamp: $TS" \
  -H "Signature: $SIG" \ \
  -H 'content-type: application/json' \
  -d '{"groupId":"sg_demo","channelId":"vip"}'

绑定用户组（批量授权）​

Shell
curl -sS -X POST "http://127.0.0.1:8080/im/v2/supergroup/usergroup/create" \
  -H 'App-Key: demo' \
  -H "Nonce: $NONCE" \
  -H "Timestamp: $TS" \
  -H "Signature: $SIG" \ \
  -H 'content-type: application/json' \
  -d '{"groupId":"sg_demo","userGroupId":"ug_vip","name":"VIP 用户"}'

curl -sS -X POST "http://127.0.0.1:8080/im/v2/supergroup/usergroup/members/add" \
  -H 'App-Key: demo' \
  -H "Nonce: $NONCE" \
  -H "Timestamp: $TS" \
  -H "Signature: $SIG" \ \
  -H 'content-type: application/json' \
  -d '{"groupId":"sg_demo","userGroupId":"ug_vip","userIds":["carol"]}'

curl -sS -X POST "http://127.0.0.1:8080/im/v2/supergroup/channel/usergroup/bind" \
  -H 'App-Key: demo' \
  -H "Nonce: $NONCE" \
  -H "Timestamp: $TS" \
  -H "Signature: $SIG" \ \
  -H 'content-type: application/json' \
  -d '{"groupId":"sg_demo","channelId":"vip","userGroupId":"ug_vip"}'

curl -sS -X POST "http://127.0.0.1:8080/im/v2/supergroup/channel/usergroup/list" \
  -H 'App-Key: demo' \
  -H "Nonce: $NONCE" \
  -H "Timestamp: $TS" \
  -H "Signature: $SIG" \ \
  -H 'content-type: application/json' \
  -d '{"groupId":"sg_demo","channelId":"vip"}'

转公开​

Shell
curl -sS -X POST "http://127.0.0.1:8080/im/v2/supergroup/channel/type/set" \
  -H 'App-Key: demo' \
  -H "Nonce: $NONCE" \
  -H "Timestamp: $TS" \
  -H "Signature: $SIG" \ \
  -H 'content-type: application/json' \
  -d '{"groupId":"sg_demo","channelId":"vip","type":"public"}'

常见问题​

私有频道能阻止群成员看到消息吗？​

当前不能。消息不带 channelId，成员关系不参与投递鉴权；必须业务侧校验或改用独立群。

私有频道支持邀请链接/密码吗？​

不支持。授权只有成员列表与用户组绑定。

切换为公开后成员列表还在吗？​

在，但公开后不再按成员限制；业务侧不要再用它做权限判断。

单频道能绑多少用户组？​

融云口径 10 个；本项目未强制，需业务侧校验。

频道成员必须是群成员吗？​

服务端只校验用户存在；业务上应先确保其已在超级群中。

相关链接​