超级群用户组操作指南

用户组（user group）是超级群内的批量授权单位：把用户加入组，再把组绑定到私有频道，组成员即被视为拥有频道访问权（产品语义）。本页给出创建 → 成员 → 绑定频道 → 按用户/频道查询 → 配额校验 → 错误码的完整流程，并说明当前不参与消息鉴权的边界。

概念​

对象接口说明
用户组usergroup/create|list|deleteuserGroupId 群内唯一
组成员usergroup/members/add|remove批量 userIds
按用户查组usergroup/by-user返回该用户所属用户组
组绑定的频道usergroup/channels按 userGroupId 或 userId 查询
频道绑定关系channel/usergroup/bind|unbind|list多对多
  • 一个用户组可绑定多个频道，一个频道可绑定多个用户组。
  • rev23 起：绑定用户组的成员计入频道有效成员（需仍是群成员），可接收/发送该频道消息。
  • 用户组数量（单群 100，超限 1015）、组成员数（单组 5000，超限 1015）由服务端强制。
当前边界

用户组参与频道消息鉴权（rev23），但“按用户组禁言/免打扰”仍未实现；客户端搜索也未按频道裁剪（Open API 搜索已过滤）。

前置条件​

  • 服务端已启动，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/usergroup/create，传 groupId、userGroupId、name。
  2. 添加组成员
    usergroup/members/add 批量加入；成员必须是已注册用户。
  3. 绑定到私有频道
    channel/usergroup/bind，把 userGroupId 绑到 channelId；解绑用 unbind。
  4. 查询授权关系

    按用户查组：usergroup/by-user；按组查频道：usergroup/channels；按频道查绑定：channel/usergroup/list。

  5. 配额校验（业务侧）

    单群用户组 ≤50、单组用户 ≤100、单频道绑定用户组 ≤10（产品口径）；服务端未强制。

    在创建/加成员/绑定前用 list 接口统计，超限返回自定义错误。

  6. 消息与错误码

    发送仍走 message.group.publish（groupId 维度）；用户组不改变消息路由。

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

参数表​

操作方法与路径请求体
创建用户组POST /im/v2/supergroup/usergroup/create{groupId,userGroupId,name}
用户组列表POST /im/v2/supergroup/usergroup/list{groupId}
删除用户组POST /im/v2/supergroup/usergroup/delete{groupId,userGroupId}
加/移成员POST /im/v2/supergroup/usergroup/members/add|remove{groupId,userGroupId,userIds[]}
按用户查组POST /im/v2/supergroup/usergroup/by-user{groupId,userId}
查组绑定频道POST /im/v2/supergroup/usergroup/channels{groupId,userGroupId} 或 {groupId,userId}
绑定/解绑POST /im/v2/supergroup/channel/usergroup/bind|unbind{groupId,channelId,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/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_ops","name":"运营组"}'

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_ops","userIds":["alice","bob"]}'

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_ops"}'

查询：用户属于哪些组、组绑定哪些频道​

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

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

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

解绑并删除组​

Shell
curl -sS -X POST "http://127.0.0.1:8080/im/v2/supergroup/channel/usergroup/unbind" \
  -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_ops"}'

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

常见问题​

用户组能用来发消息吗？​

不能。用户组只用于授权关系；消息仍按 groupId 发送到整个超级群。

组成员会自动加入频道吗？​

不会产生频道成员记录；绑定关系表示产品语义上的访问权，需业务侧读取绑定结果判断。

删除用户组会删频道吗？​

不会。只删除组与成员关系；已绑定的频道仍在，绑定关系需先解绑或随组删除清理。

单组最多多少用户？​

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

为什么 by-user 返回空？​

确认用户已加入该组、groupId 正确；用户不存在返回 1004。

相关链接​