超级群频道与用户组

超级群（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` 共享状态。

client.createSupergroupChannel(
    params = CreateSupergroupChannelParams(groupId = "g_1001", name = "产品群", type = "public"),
    callback = object : ResultCallback<SupergroupChannel> {
        override fun onSuccess(result: SupergroupChannel) { /* 处理返回数据 */ }
        override fun onError(error: IMError) { /* 处理 error.code */ }
    },
)

listSupergroupChannels​

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

client.listSupergroupChannels(
    groupId = "g_1001",
    callback = object : ResultCallback<SupergroupChannelListResult> {
        override fun onSuccess(result: SupergroupChannelListResult) { /* 处理返回数据 */ }
        override fun onError(error: IMError) { /* 处理 error.code */ }
    },
)

joinSupergroupChannel​

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

client.joinSupergroupChannel(
    channelId = "ch_1001",
    callback = object : ResultCallback<JoinSupergroupChannelResult> {
        override fun onSuccess(result: JoinSupergroupChannelResult) { /* 处理返回数据 */ }
        override fun onError(error: IMError) { /* 处理 error.code */ }
    },
)

leaveSupergroupChannel​

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

client.leaveSupergroupChannel(
    channelId = "ch_1001",
    callback = object : ResultCallback<LeaveSupergroupChannelResult> {
        override fun onSuccess(result: LeaveSupergroupChannelResult) { /* 处理返回数据 */ }
        override fun onError(error: IMError) { /* 处理 error.code */ }
    },
)

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。

client.bindUserGroupToChannel(
    channelId = "ch_1001",
    userGroupId = "ug_1001",
    callback = object : ResultCallback<BindUserGroupToChannelResult> {
        override fun onSuccess(result: BindUserGroupToChannelResult) { /* 处理返回数据 */ }
        override fun onError(error: IMError) { /* 处理 error.code */ }
    },
)

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.*` 共享状态。

client.createUserGroup(
    params = CreateUserGroupParams(groupId = "g_1001", name = "产品群"),
    callback = object : ResultCallback<UserGroup> {
        override fun onSuccess(result: UserGroup) { /* 处理返回数据 */ }
        override fun onError(error: IMError) { /* 处理 error.code */ }
    },
)

listUserGroups​

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

client.listUserGroups(
    groupId = "g_1001",
    callback = object : ResultCallback<UserGroupListResult> {
        override fun onSuccess(result: UserGroupListResult) { /* 处理返回数据 */ }
        override fun onError(error: IMError) { /* 处理 error.code */ }
    },
)

getUserGroupsByUser​

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

client.getUserGroupsByUser(
    userId = "user2",
    callback = object : ResultCallback<UserGroupListResult> {
        override fun onSuccess(result: UserGroupListResult) { /* 处理返回数据 */ }
        override fun onError(error: IMError) { /* 处理 error.code */ }
    },
)

相关文档​

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