超级群频道与用户组

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

rev22/rev23：超级群会话类型与频道消息

rev22 起超级群会话类型为 SUPER_GROUP(10)；存量 GROUP(2)+groupType=super 仍可读，两者共用同一群会话键（g:{groupId}）。

rev23 起消息可带 options.channelId 按频道投递（仅频道成员接收、历史可按频道过滤）；不带 channelId 为群级消息。频道/用户组管理接口仍按 groupId 工作。

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

平台调用风格

C ABI 约定：im_client_* 返回 int（0 成功，非 0 为 IDL 错误码）；char** out_json 由库分配、调用方用 im_string_free 释放；char* out + size_t cap 为调用方缓冲区（0 成功 / -1 参数非法 / -2 缓冲区不足）。

接口一览​

操作语义传输返回
createSupergroupChannel创建超级群频道（IDL rev21 C17；客户端 REST `POST /api/apps/{appkey}/supergroup/channels`）→ SupergroupChannel。channelId 服务端生成（`ch_<uuid>`，应用内唯一）；joinPolicy 由 type 推导（public→open、private→invite），与之矛盾的显式取值 1001；仅群主/管理员可调用（否则 1003），群不存在 1005，单群 100 频道上限（超限 1015）。与 Open API `supergroup.channel.create` 共享状态。REST（客户端）SupergroupChannel
listSupergroupChannels超级群频道列表（IDL rev21 C17；客户端 REST `GET /api/apps/{appkey}/supergroup/channels?groupId=`）→ `{groupId,channels:[SupergroupChannel],total}`。仅群成员可读（否则 1003），群不存在 1005，缺 groupId 1001。REST（客户端）{groupId:string, channels:SupergroupChannel[], total:uint32}
joinSupergroupChannel加入超级群频道（IDL rev21 C17；客户端 REST `POST .../supergroup/channels/{channelId}/join`，幂等）→ `{groupId,channelId,userId,joined:true,alreadyJoined}`。public 频道群成员可直接加入；private 频道需已受邀或为群主/管理员（否则 1003）。频道不存在 1005；channelId 跨群同名时可通过第二参数 `{groupId}` 消歧（未消歧 1001）；非群成员 1003。REST（客户端）{groupId:string, channelId:string, userId:string, joined:bool, alreadyJoined:bool}
leaveSupergroupChannel离开超级群频道（IDL rev21 C17；客户端 REST `POST .../supergroup/channels/{channelId}/leave`，幂等）→ `{groupId,channelId,userId,left:true,wasMember}`；不在频道内也返回成功（wasMember=false）。频道不存在 1005、非群成员 1003。REST（客户端）{groupId:string, channelId:string, userId:string, left:bool, wasMember:bool}
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。REST（客户端）{groupId:string, channelId:string, userGroupId:string, bound:bool, reverseIndexed:bool}
createUserGroup创建超级群用户组（IDL rev21 C17；客户端 REST `POST /api/apps/{appkey}/supergroup/usergroups`）→ UserGroup。userGroupId 服务端生成（`ug_<uuid>`）；members 去空/去重/保序，每项必须是本群成员（否则 1003）、用户不存在 1004；仅群主/管理员（否则 1003）；参数非法 1001、单群 100 用户组上限（超限 1015）。与 Open API `supergroup.usergroup.*` 共享状态。REST（客户端）UserGroup
listUserGroups超级群用户组列表（IDL rev21 C17；客户端 REST `GET /api/apps/{appkey}/supergroup/usergroups?groupId=`）→ `{groupId,userGroups:[UserGroup],total}`；UserGroup.channelIds 为频道反向索引（rev21 修复后可用）。仅群成员可读（否则 1003），群不存在 1005，缺 groupId 1001。REST（客户端）{groupId:string, userGroups:UserGroup[], total:uint32}
getUserGroupsByUser查询某用户所在的所有用户组（IDL rev21 C17；客户端 REST `GET .../supergroup/usergroups/by-user/{userId}`）→ `{userId,userGroups:[UserGroup],total}`。仅本人可查（userId ≠ 当前登录用户 1003）；`options.groupId` 可限定单个群；只返回「本人确实在该群」的用户组（群已删除的不返回，不虚构）。REST（客户端）{userId:string, userGroups:UserGroup[], total:uint32}

本页 8 个操作，其中 0 个在本平台绑定中声明了方法签名，其余为 C ABI 未暴露（见对应小节）。

跨端方法名​

操作AndroidWebElectronmacOSFlutterNative (C ABI)iOS
createSupergroupChannelcreateSupergroupChannelcreateSupergroupChannelcreateSupergroupChannelcreateSupergroupChannelcreateSupergroupChannel—func
listSupergroupChannelslistSupergroupChannelslistSupergroupChannelslistSupergroupChannelslistSupergroupChannelslistSupergroupChannels—func
joinSupergroupChanneljoinSupergroupChanneljoinSupergroupChanneljoinSupergroupChanneljoinSupergroupChanneljoinSupergroupChannel—func
leaveSupergroupChannelleaveSupergroupChannelleaveSupergroupChannelleaveSupergroupChannelleaveSupergroupChannelleaveSupergroupChannel—func
bindUserGroupToChannelbindUserGroupToChannelbindUserGroupToChannelbindUserGroupToChannelbindUserGroupToChannelbindUserGroupToChannel—func
createUserGroupcreateUserGroupcreateUserGroupcreateUserGroupcreateUserGroupcreateUserGroup—func
listUserGroupslistUserGroupslistUserGroupslistUserGroupslistUserGroupslistUserGroups—func
getUserGroupsByUsergetUserGroupsByUsergetUserGroupsByUsergetUserGroupsByUsergetUserGroupsByUsergetUserGroupsByUser—func

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

C ABI 未暴露

本页操作均未在正式 C ABI（include/im_sdk.h）中暴露。C ABI 当前覆盖 18 个操作：init / connect / disconnect / getConnectionStatus / getCurrentUserId / sendTextMessage / sendMessage / recallMessage / sendReadReceipt / getConversationList / getHistoryMessages / getGroupMembers / joinChatroom / leaveChatroom / getChatroomInfo / uploadFile / addEventListener / removeEventListener。其余能力请使用其它平台绑定，或通过服务端 Open API 完成。

替代路径说明
服务端 Open API群组模块接口：在服务端批量管理消息、会话、群组与用户
Web / Electron / Flutter / Android 绑定这些绑定覆盖全部 62 个语义 op；可通过服务端中转或由另一进程执行后回调 Native 侧

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

本平台 C ABI 未暴露该方法
REST（客户端）since 1.5.0

本操作未在 native C ABI（include/im_sdk.h）暴露；如需该能力，请使用 Web / Electron / Flutter / Android 绑定，或通过服务端 Open API 完成。

参数
参数类型说明
params{groupId:string, name:string, type:ChannelType, joinPolicy?:JoinPolicy}必填；对象：{ groupId:string, name:string, type:ChannelType, joinPolicy?:JoinPolicy }
返回

SupergroupChannel 成功返回的数据；失败时按错误码处理

错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1002INVALID_TOKEN客户端 / 参数 / 权限401否Token 无效或已过期
1003FORBIDDEN客户端 / 参数 / 权限403否无权限
1005GROUP_NOT_FOUND客户端 / 参数 / 权限404否群组不存在
1015MEMBERSHIP_LIMIT客户端 / 参数 / 权限400否成员数量超出上限

listSupergroupChannels​

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

本平台 C ABI 未暴露该方法
REST（客户端）幂等since 1.5.0

本操作未在 native C ABI（include/im_sdk.h）暴露；如需该能力，请使用 Web / Electron / Flutter / Android 绑定，或通过服务端 Open API 完成。

参数
参数类型说明
groupIdstring必填；群组 ID
返回

{groupId:string, channels:SupergroupChannel[], total:uint32} 成功返回的数据；失败时按错误码处理

错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1002INVALID_TOKEN客户端 / 参数 / 权限401否Token 无效或已过期
1003FORBIDDEN客户端 / 参数 / 权限403否无权限
1005GROUP_NOT_FOUND客户端 / 参数 / 权限404否群组不存在

joinSupergroupChannel​

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

本平台 C ABI 未暴露该方法
REST（客户端）幂等since 1.5.0

本操作未在 native C ABI（include/im_sdk.h）暴露；如需该能力，请使用 Web / Electron / Flutter / Android 绑定，或通过服务端 Open API 完成。

参数
参数类型说明
channelIdstring必填；字段含义见类型定义
options{groupId?:string}可选；选项对象（字段见类型列）：{ groupId?:string }
返回

{groupId:string, channelId:string, userId:string, joined:bool, alreadyJoined:bool} 成功返回的数据；失败时按错误码处理

错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1002INVALID_TOKEN客户端 / 参数 / 权限401否Token 无效或已过期
1003FORBIDDEN客户端 / 参数 / 权限403否无权限
1005GROUP_NOT_FOUND客户端 / 参数 / 权限404否群组不存在

leaveSupergroupChannel​

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

本平台 C ABI 未暴露该方法
REST（客户端）幂等since 1.5.0

本操作未在 native C ABI（include/im_sdk.h）暴露；如需该能力，请使用 Web / Electron / Flutter / Android 绑定，或通过服务端 Open API 完成。

参数
参数类型说明
channelIdstring必填；字段含义见类型定义
options{groupId?:string}可选；选项对象（字段见类型列）：{ groupId?:string }
返回

{groupId:string, channelId:string, userId:string, left:bool, wasMember:bool} 成功返回的数据；失败时按错误码处理

错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1002INVALID_TOKEN客户端 / 参数 / 权限401否Token 无效或已过期
1003FORBIDDEN客户端 / 参数 / 权限403否无权限
1005GROUP_NOT_FOUND客户端 / 参数 / 权限404否群组不存在

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。

本平台 C ABI 未暴露该方法
REST（客户端）幂等since 1.5.0

本操作未在 native C ABI（include/im_sdk.h）暴露；如需该能力，请使用 Web / Electron / Flutter / Android 绑定，或通过服务端 Open API 完成。

参数
参数类型说明
channelIdstring必填；字段含义见类型定义
userGroupIdstring必填；字段含义见类型定义
options{groupId?:string}可选；选项对象（字段见类型列）：{ groupId?:string }
返回

{groupId:string, channelId:string, userGroupId:string, bound:bool, reverseIndexed:bool} 成功返回的数据；失败时按错误码处理

错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1002INVALID_TOKEN客户端 / 参数 / 权限401否Token 无效或已过期
1003FORBIDDEN客户端 / 参数 / 权限403否无权限
1005GROUP_NOT_FOUND客户端 / 参数 / 权限404否群组不存在

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

本平台 C ABI 未暴露该方法
REST（客户端）since 1.5.0

本操作未在 native C ABI（include/im_sdk.h）暴露；如需该能力，请使用 Web / Electron / Flutter / Android 绑定，或通过服务端 Open API 完成。

参数
参数类型说明
params{groupId:string, name:string, members?:string[]}必填；对象：{ groupId:string, name:string, members?:string[] }
返回

UserGroup 成功返回的数据；失败时按错误码处理

错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1002INVALID_TOKEN客户端 / 参数 / 权限401否Token 无效或已过期
1003FORBIDDEN客户端 / 参数 / 权限403否无权限
1004USER_NOT_FOUND客户端 / 参数 / 权限404否用户不存在
1015MEMBERSHIP_LIMIT客户端 / 参数 / 权限400否成员数量超出上限

listUserGroups​

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

本平台 C ABI 未暴露该方法
REST（客户端）幂等since 1.5.0

本操作未在 native C ABI（include/im_sdk.h）暴露；如需该能力，请使用 Web / Electron / Flutter / Android 绑定，或通过服务端 Open API 完成。

参数
参数类型说明
groupIdstring必填；群组 ID
返回

{groupId:string, userGroups:UserGroup[], total:uint32} 成功返回的数据；失败时按错误码处理

错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1002INVALID_TOKEN客户端 / 参数 / 权限401否Token 无效或已过期
1003FORBIDDEN客户端 / 参数 / 权限403否无权限
1005GROUP_NOT_FOUND客户端 / 参数 / 权限404否群组不存在

getUserGroupsByUser​

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

本平台 C ABI 未暴露该方法
REST（客户端）幂等since 1.5.0

本操作未在 native C ABI（include/im_sdk.h）暴露；如需该能力，请使用 Web / Electron / Flutter / Android 绑定，或通过服务端 Open API 完成。

参数
参数类型说明
userIdstring必填；用户 ID
options{groupId?:string}可选；选项对象（字段见类型列）：{ groupId?:string }
返回

{userId:string, userGroups:UserGroup[], total:uint32} 成功返回的数据；失败时按错误码处理

错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1002INVALID_TOKEN客户端 / 参数 / 权限401否Token 无效或已过期
1003FORBIDDEN客户端 / 参数 / 权限403否无权限

相关文档​