超级群频道与用户组

超级群（groupType=super；rev22 起会话类型 SUPER_GROUP(10)，存量 GROUP(2)+super 仍可读）的频道与用户组：频道创建/查询/加入/退出，用户组增查与频道绑定，用于按主题或组织维度组织成员；消息按超级群会话收发（无 channelId 隔离）。

完整用法与兼容规则：超级群会话类型、超级群频道级消息、频道消息迁移、迁移与兼容 FAQ。

接口一览​

本页 8 个操作，其中 8 个在本平台绑定中声明了方法签名。

跨端方法名​

方法名在 GA 平台之间保持一致（规则 A）；Native C ABI 只覆盖部分操作，其余操作以 — 标注。

createSupergroupChannel​

创建超级群频道（IDL rev21 C17；客户端 REST `POST /api/apps/{appkey}/supergroup/channels`）→ SupergroupChannel。channelId 服务端生成（`ch_`，应用内唯一）；joinPolicy 由 type 推导（public→open、private→invite），与之矛盾的显式取值 1001；仅群主/管理员可调用（否则 1003），群不存在 1005，单群 100 频道上限（超限 1015）。与 Open API `supergroup.channel.create` 共享状态。

const res = await client.createSupergroupChannel({ groupId: 'g_1001', name: '产品群', type: 'public' });
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

listSupergroupChannels​

超级群频道列表（IDL rev21 C17；客户端 REST `GET /api/apps/{appkey}/supergroup/channels?groupId=`）→ `{groupId,channels:[SupergroupChannel],total}`。仅群成员可读（否则 1003），群不存在 1005，缺 groupId 1001。

const res = await client.listSupergroupChannels('g_1001');
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

joinSupergroupChannel​

加入超级群频道（IDL rev21 C17；客户端 REST `POST .../supergroup/channels/{channelId}/join`，幂等）→ `{groupId,channelId,userId,joined:true,alreadyJoined}`。public 频道群成员可直接加入；private 频道需已受邀或为群主/管理员（否则 1003）。频道不存在 1005；channelId 跨群同名时可通过第二参数 `{groupId}` 消歧（未消歧 1001）；非群成员 1003。

const res = await client.joinSupergroupChannel('ch_1001');
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

leaveSupergroupChannel​

离开超级群频道（IDL rev21 C17；客户端 REST `POST .../supergroup/channels/{channelId}/leave`，幂等）→ `{groupId,channelId,userId,left:true,wasMember}`；不在频道内也返回成功（wasMember=false）。频道不存在 1005、非群成员 1003。

const res = await client.leaveSupergroupChannel('ch_1001');
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

bindUserGroupToChannel​

把用户组绑定到频道（IDL rev21 C17；客户端 REST `POST .../supergroup/channels/{channelId}/usergroups`，幂等）→ `{groupId,channelId,userGroupId,bound:true,reverseIndexed}`。**双向维护** SupergroupChannel.userGroupIds 与 UserGroup.channelIds（rev21 修复 rev7 仅写频道侧导致的反向索引缺失），因此 `listUserGroups`/`getUserGroupsByUser` 的 channelIds 反查可用。仅群主/管理员（否则 1003）；频道/用户组不存在 1005。

const res = await client.bindUserGroupToChannel('ch_1001', 'ug_1001');
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

createUserGroup​

创建超级群用户组（IDL rev21 C17；客户端 REST `POST /api/apps/{appkey}/supergroup/usergroups`）→ UserGroup。userGroupId 服务端生成（`ug_`）；members 去空/去重/保序，每项必须是本群成员（否则 1003）、用户不存在 1004；仅群主/管理员（否则 1003）；参数非法 1001、单群 100 用户组上限（超限 1015）。与 Open API `supergroup.usergroup.*` 共享状态。

const res = await client.createUserGroup({ groupId: 'g_1001', name: '产品群' });
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

listUserGroups​

超级群用户组列表（IDL rev21 C17；客户端 REST `GET /api/apps/{appkey}/supergroup/usergroups?groupId=`）→ `{groupId,userGroups:[UserGroup],total}`；UserGroup.channelIds 为频道反向索引（rev21 修复后可用）。仅群成员可读（否则 1003），群不存在 1005，缺 groupId 1001。

const res = await client.listUserGroups('g_1001');
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

getUserGroupsByUser​

查询某用户所在的所有用户组（IDL rev21 C17；客户端 REST `GET .../supergroup/usergroups/by-user/{userId}`）→ `{userId,userGroups:[UserGroup],total}`。仅本人可查（userId ≠ 当前登录用户 1003）；`options.groupId` 可限定单个群；只返回「本人确实在该群」的用户组（群已删除的不返回，不虚构）。

const res = await client.getUserGroupsByUser('user2');
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

相关文档​

• 功能列表：103 个操作与签名
• 状态码：错误码与重试策略
• API 参考：类与成员
• IMLib 集成指南