超级群频道操作指南

频道（channel）是超级群内的讨论分区：超级群保存成员关系，频道保存类型（public/private）、名称与成员列表。本页以公开频道为主线，给出创建 → 成员 → 频道消息（rev23）→ 配额校验 → 错误码的完整操作，并标注频道级 typing/搜索等未覆盖项。

概念​

对象字段说明
超级群groupId + groupType=super成员上限更高；加入策略 invite/open；rev22 起会话类型 SUPER_GROUP(10)（存量 2+super 可读）
频道channelId/name/typetype 缺省 private；公开频道对所有超级群成员可见
频道成员userIds[]私有频道按成员授权；公有频道成员列表是频道消息收件人范围（rev23）
消息message.group.publish 的 groupId + 可选 channelIdrev23：带 channelId 按频道投递（仅频道成员接收）；不带为群级消息；会话类型 10
  • 本项目不自动创建默认频道（融云的 RCDefault 未实现）；频道必须显式创建。
  • 配额已强制：单群 100 个频道、100 个用户组（超限 1015）、单用户组 5000 名成员、名称 ≤64 字。
  • 删除频道只删除频道记录与成员关系；此后向该频道发送返回 1005，群历史不再返回该频道消息。
当前边界

频道消息路由已实现（rev23）：发送时带 channelId 即只投递给频道成员，历史可按频道过滤。仍有限制：频道级 typing/搜索裁剪、频道消息独立会话与未读拆分、默认频道/默认免打扰未实现；IMKit 只提供单频道会话视图（选择器/成员页需宿主实现）。

前置条件​

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

步骤​

  1. 创建超级群（若还没有）
    POST /group/create，传 groupId、name、owner、members 与 groupType:"super"。返回 Group，成员上限为超级群上限。
  2. 创建公开频道
    POST /supergroup/channel/create，type 显式传 public；channelId 在群内唯一。
  3. 维护频道成员

    公开频道通常不需要成员列表；如需展示订阅者，可用 channel/members/add 维护。私有频道的授权语义见「私有频道操作指南」。

  4. 发送消息（群级 / 频道）
    POST /message/group/publish：只传 groupId 为群级消息（全部群成员）；加 channelId 为频道消息（仅频道成员接收，私有频道需发送者是频道成员，否则 1003）。超级群消息会话类型为 10。
  5. 配额校验

    服务端已强制：单群 100 个频道、100 个用户组、单用户组 5000 名成员；超限返回 1015。

    业务侧仍建议在创建前提示容量，避免用户填写后再失败；不要用“删除重建”规避配额（会丢频道成员/绑定关系）。

  6. 按错误码处置
    1021 未开通 supergroup；1004 用户或群不存在（supergroup 实现把群不存在映射为 1004）；1003 无权限；1001 参数非法。

参数表​

操作方法与路径请求体
创建超级群POST /im/v2/group/create{groupId?,name,owner,members?,groupType:"super"}
创建频道POST /im/v2/supergroup/channel/create{groupId,channelId,name?,type?}
频道列表POST /im/v2/supergroup/channel/list{groupId}
频道类型POST /im/v2/supergroup/channel/type/set{groupId,channelId,type}
删除频道POST /im/v2/supergroup/channel/delete{groupId,channelId}
频道成员POST /im/v2/supergroup/channel/members/add|remove|list{groupId,channelId,userIds?}
发群消息POST /im/v2/message/group/publish{fromUserId,groupId,content,clientMsgId?,channelId?}；带 channelId 为频道消息（rev23），超级群消息落库 conversationType=10

示例​

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

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'))")"

创建 super 群 → 创建公开频道 → 查列表​

Shell
curl -sS -X POST "http://127.0.0.1:8080/im/v2/group/create" \
  -H 'App-Key: demo' \
  -H "Nonce: $NONCE" \
  -H "Timestamp: $TS" \
  -H "Signature: $SIG" \ \
  -H 'content-type: application/json' \
  -d '{"groupId":"sg_demo","name":"社区超级群","owner":"alice","members":["alice","bob"],"groupType":"super"}'

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":"news","name":"公告","type":"public"}'

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

向超级群发送群级消息（无 channelId）​

Shell
curl -sS -X POST "http://127.0.0.1:8080/im/v2/message/group/publish" \
  -H 'App-Key: demo' \
  -H "Nonce: $NONCE" \
  -H "Timestamp: $TS" \
  -H "Signature: $SIG" \ \
  -H 'content-type: application/json' \
  -d '{"fromUserId":"alice","groupId":"sg_demo","content":{"type":"text","text":"大家好，这是群级消息"},"clientMsgId":"c-1001"}'

向超级群发送频道消息（带 channelId，rev23）​

Shell
curl -sS -X POST "http://127.0.0.1:8080/im/v2/message/group/publish" \
  -H 'App-Key: demo' \
  -H "Nonce: $NONCE" \
  -H "Timestamp: $TS" \
  -H "Signature: $SIG" \ \
  -H 'content-type: application/json' \
  -d '{"fromUserId":"alice","groupId":"sg_demo","channelId":"news","content":{"type":"text","text":"只发给公告频道成员"},"clientMsgId":"c-1002"}'

删除频道​

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

常见问题​

消息能只发到某个频道吗？​

可以（rev23）：发送时带 channelId，仅该频道成员接收；不带 channelId 是群级消息。私有频道要求发送者是频道成员（否则 1003），公有频道群成员发送会自动加入。

公开频道需要加成员吗？​

服务端按频道成员投递：公开频道群成员发送时自动加入；只读展示可不加成员。历史读取对群成员开放。

单群最多多少频道？​

本项目强制 100 个频道、100 个用户组（超限 1015）。

删除频道会影响历史消息吗？​

删除频道后不能再向该频道发送（1005）；群历史不再返回该频道消息（频道不存在视为不可见）。

为什么创建频道返回 1021？​

应用未开通 supergroup 服务；在控制台「服务开通」开启后重试。

相关链接​