IMClient 类（Android IMLib）

初始化 SDK（构造客户端实例）。幂等：同 appkey 重复初始化返回同一实例。 可能错误码：1001 参数错误。 该操作幂等：重复调用不会产生额外副作用。

IMClient 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

val client = IMClient.init(
    context = applicationContext,
    options = IMClientOptions(
        appkey = "<appkey>",
        serverUrl = "http://127.0.0.1:8080",
    ),
)

使用用户 token 建立长连接：握手→hello→离线补发→sync_done；成功后触发 CONNECTED。失败按协议重连策略重试。 可能错误码：1002 Token 无效或已过期、1016 账号已被封禁、1017 应用已停用、2001 服务端内部错误、2002 依赖服务不可用、3002 请求超时、3003 网络错误。 可能触发事件：CONNECTING、CONNECTED。

{userId:string, sessionId?:string} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.connect(token = "<user-token>", callback = callback /* ConnectCallback：实现后由主线程回调 */)

主动断开；停止重连、清理心跳与待决请求。 可能错误码：无特定错误码（通用错误见 ErrorCode）。 该操作幂等：重复调用不会产生额外副作用。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

client.disconnect(receivePush = null)

返回 ConnectionStatus 枚举值。 可能错误码：无特定错误码（通用错误见 ErrorCode）。

ConnectionStatus 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getConnectionStatus()

当前登录 userId；未登录返回空串。 可能错误码：无特定错误码（通用错误见 ErrorCode）。

string 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getCurrentUserId()

注册事件监听；同一 handler 重复注册只生效一次。 可能错误码：无特定错误码（通用错误见 ErrorCode）。 该操作幂等：重复调用不会产生额外副作用。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

val handler = object : EventHandler {
    // 实现事件回调
}
client.addEventListener(IMClientEvent.MESSAGES, handler)

移除事件监听。 可能错误码：无特定错误码（通用错误见 ErrorCode）。 该操作幂等：重复调用不会产生额外副作用。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

val handler = object : EventHandler {
    // 实现事件回调
}
client.removeEventListener(IMClientEvent.MESSAGES, handler)

发送任意类型消息。优先走长连接；连接不可用（SUSPEND/DISCONNECTED）时按 SDK_NO_CONNECTION 失败并保留本地待发队列（可选实现）。rev23：options.channelId 用于超级群频道消息（conversationType=10），仅频道成员接收；消息模型带 channelId。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在、1005 群组不存在、1006 未加入群组、1007 消息体过大（上限 5KB）、1008 发送过于频繁、1009 你已被禁言、1010 内容包含敏感词、1011 已被对方拉黑或你已拉黑对方 等 17 个。 可能触发事件：MESSAGES、CONVERSATION。

Message 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.sendMessage(conversationType = ConversationType.PRIVATE, targetId = "user_001", content = TextContent("Hello, NI PaaS!"), options = null, callback = callback /* SendMessageCallback：实现后由主线程回调 */)

发送文本消息；内部等价 sendMessage(content={type:'text',text,mentionedInfo?,quote?})。 可能错误码：1001 参数错误、1007 消息体过大（上限 5KB）、1009 你已被禁言、1010 内容包含敏感词、1011 已被对方拉黑或你已拉黑对方、3001 长连接未就绪、3002 请求超时。

Message 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.sendTextMessage(conversationType = ConversationType.PRIVATE, targetId = "user_001", text = "Hello, NI PaaS!", options = null, callback = callback /* SendMessageCallback：实现后由主线程回调 */)

发送图片消息；url 由 uploadFile 或业务方上传得到。 可能错误码：1001 参数错误、1007 消息体过大（上限 5KB）、1009 你已被禁言、1011 已被对方拉黑或你已拉黑对方、3001 长连接未就绪。

Message 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.sendImageMessage(conversationType = ConversationType.PRIVATE, targetId = "user_001", content = TextContent("Hello, NI PaaS!"), options = null, callback = callback /* SendMessageCallback：实现后由主线程回调 */)

发送文件消息。 可能错误码：1001 参数错误、1007 消息体过大（上限 5KB）、1009 你已被禁言、1011 已被对方拉黑或你已拉黑对方、3001 长连接未就绪。

Message 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.sendFileMessage(conversationType = ConversationType.PRIVATE, targetId = "user_001", content = TextContent("Hello, NI PaaS!"), options = null, callback = callback /* SendMessageCallback：实现后由主线程回调 */)

发送语音消息；duration 秒 1..300。 可能错误码：1001 参数错误、1007 消息体过大（上限 5KB）、1009 你已被禁言、1011 已被对方拉黑或你已拉黑对方、3001 长连接未就绪。

Message 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.sendVoiceMessage(conversationType = ConversationType.PRIVATE, targetId = "user_001", content = TextContent("Hello, NI PaaS!"), options = null, callback = callback /* SendMessageCallback：实现后由主线程回调 */)

发送位置消息；lat/lng 范围校验。 可能错误码：1001 参数错误、1007 消息体过大（上限 5KB）、1009 你已被禁言、1011 已被对方拉黑或你已拉黑对方、3001 长连接未就绪。

Message 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.sendLocationMessage(conversationType = ConversationType.PRIVATE, targetId = "user_001", content = TextContent("Hello, NI PaaS!"), options = null, callback = callback /* SendMessageCallback：实现后由主线程回调 */)

发送正在输入状态；不持久化；对端触发 TYPING 事件。 可能错误码：1004 用户不存在、1005 群组不存在、1006 未加入群组、1008 发送过于频繁、3001 长连接未就绪。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

client.sendTypingStatus(conversationType = ConversationType.PRIVATE, targetId = "user_001", typing = true, callback = callback /* OperationCallback?：实现后由主线程回调 */)

撤回消息（仅发送者、撤回时限内）。成功后本地与对端收到 MESSAGE_RECALLED。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在、1022 超过撤回时限、1023 消息已撤回、3001 长连接未就绪。 可能触发事件：MESSAGE_RECALLED、CONVERSATION。

Message 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.recallMessage(messageId = "msg_001", options = null, callback = callback /* ResultCallback<Message>：实现后由主线程回调 */)

上报已读回执；服务端记录唯一读者并推送给消息发送者。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在、3001 长连接未就绪。 可能触发事件：READ_RECEIPT。

{messageIds:string[], readCounts?:map<string,uint32>, totalMembers?:uint32} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.sendReadReceipt(conversationType = ConversationType.PRIVATE, targetId = "user_001", messageIds = ["msg_001"], callback = callback /* ResultCallback<ReadReceiptResult>：实现后由主线程回调 */)

查询消息已读人数。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在。

{messageId:string, readCount:uint32, totalMembers:uint32} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getMessageReadCount(messageId = "msg_001", callback = callback /* ResultCallback<MessageReadCount>：实现后由主线程回调 */)

查询已读用户明细（分页）。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在。

{messageId:string, readCount:uint32, totalMembers:uint32, readers:UserProfile[]} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getMessageReadUsers(messageId = "msg_001", options = null, callback = callback /* ResultCallback<MessageReadUsers>：实现后由主线程回调 */)

查询单条消息的已读详情：已读/未读名单 + 具体读取时间（分页；filter=all|read|unread，默认 all）。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在。

{messageId:string, readCount:uint32, unreadCount:uint32, totalMembers:uint32, filter:string, offset:uint32, limit:uint32, total:uint32, hasMore:boolean, items:MessageReadDetailItem[]} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getMessageReadDetail(messageId = "msg_001", options = null, callback = callback /* ResultCallback<MessageReadDetail>：实现后由主线程回调 */)

在当前用户全部会话中搜索文本消息（倒序）。 可能错误码：1001 参数错误、1003 无权限。

{messages:Message[], total:uint32} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.searchMessages(options = SearchMessagesOptions(keyword = "ni"), callback = callback /* ResultCallback<MessageSearchResult>：实现后由主线程回调 */)

更新已发送消息的扩展 KV（合并语义）。仅单聊/群聊/超级群支持，且消息须在发送时开启可扩展；单次 ≤20 对、单条 ≤300 对，key 1-32 字符 [A-Za-z0-9+=_-]、value ≤4096。 可能错误码：1001 参数错误、1004 用户不存在、1026 消息不可扩展（发送时未开启可扩展，或会话类型不支持）、1027 消息扩展超出限制（单次 20 对 / 单条 300 对 / 键值长度）。

{messageId:string, expansion:Record<string,string>} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.updateMessageExpansion(messageId = "msg_001", expansion = null, String> = null, callback = callback /* OperationCallback?：实现后由主线程回调 */)

删除消息扩展 KV（按 key）。语义与融云 removeMessageExpansion 对齐：消息须可扩展，删除不存在的 key 不报错。 可能错误码：1001 参数错误、1004 用户不存在、1026 消息不可扩展（发送时未开启可扩展，或会话类型不支持）。

{messageId:string, removed:string[], expansion:Record<string,string>} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.removeMessageExpansion(messageId = "msg_001", keys = null, callback = callback /* OperationCallback?：实现后由主线程回调 */)

为指定消息添加回应（reactionId 由业务定义，1-16 字符；同一用户对同一消息同一 reactionId 重复添加视为幂等）。单条消息最多 50 种回应、每种回应最多 100 个用户。 可能错误码：1001 参数错误、1004 用户不存在、1028 回应标识非法（1-16 字符）、1029 单条消息回应种类超出上限（50）、1030 单个回应参与用户超出上限（100）。

{messageId:string, reactionId:string, userId:string, reactionTime:uint64} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.addMessageReaction(conversationType = ConversationType.PRIVATE, targetId = "user_001", messageId = "msg_001", reactionId = null, callback = callback /* ResultCallback<MessageReaction>?：实现后由主线程回调 */)

移除自己对指定消息的回应；reactionId 须与添加时一致，未添加过时返回成功（removed=false）。 可能错误码：1001 参数错误、1004 用户不存在、1028 回应标识非法（1-16 字符）。

{messageId:string, reactionId:string, removed:boolean} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.removeMessageReaction(conversationType = ConversationType.PRIVATE, targetId = "user_001", messageId = "msg_001", reactionId = null, callback = callback /* OperationCallback?：实现后由主线程回调 */)

批量查询消息回应摘要（1-100 个 messageId）。返回按 messageId 分组：每个回应含总数、当前用户是否已回应、最近参与用户（最多 10 个）；不存在回应的消息返回空数组。 可能错误码：1001 参数错误、1004 用户不存在。

Record<string, ReactionSummary[]>（ReactionSummary={reactionId:string,totalCount:uint32,hasCurrentUserReacted:boolean,reactionTime:uint64,users:{userId:string,reactionTime:uint64}[]}） 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.batchGetMessageReactionSummaries(conversationType = ConversationType.PRIVATE, targetId = "user_001", messageIds = ["msg_001"], callback = callback /* ResultCallback<Map<String：实现后由主线程回调 */)

分页查询指定消息的回应列表（count 1-50，默认 20；pageToken 不透明，空串表示第一页）。 可能错误码：1001 参数错误、1004 用户不存在。

{reactions:ReactionSummary[], pageToken?:string, totalCount:uint32} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getMessageReactions(conversationType = ConversationType.PRIVATE, targetId = "user_001", messageId = "msg_001", count = null, pageToken = null, callback = callback /* ResultCallback<MessageReactionPage>?：实现后由主线程回调 */)

分页查询某个回应的参与用户（count 1-50，默认 20；pageToken 不透明）。 可能错误码：1001 参数错误、1004 用户不存在、1028 回应标识非法（1-16 字符）。

{users:{userId:string,reactionTime:uint64}[], pageToken?:string, totalCount:uint32} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getMessageReactionUsers(conversationType = ConversationType.PRIVATE, targetId = "user_001", messageId = "msg_001", reactionId = null, count = null, pageToken = null, callback = callback /* ResultCallback<MessageReactionUserPage>?：实现后由主线程回调 */)

开始一条流式消息（IDL rev17；客户端 REST `POST /api/apps/{appkey}/messages/stream/start`）。发送者取自用户 token；`content.text` 作为初始文本。返回 StreamMessage（streamId/messageId/status='streaming'/createdAt/text/segments），SDK 本地保留一个可增量渲染的流式占位消息。支持单聊（1）、群聊（2）、系统通知（4）；聊天室（3）暂不支持（1001）。 可能错误码：1001 参数错误、1004 用户不存在、1005 群组不存在。

StreamMessage 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.startStreamMessage(conversationType = ConversationType.PRIVATE, targetId = "user_001", options = null, callback = callback /* ResultCallback<StreamMessage>?：实现后由主线程回调 */)

追加一个流式增量（IDL rev17；客户端 REST `POST /api/apps/{appkey}/messages/stream/append`），返回累计文本/分段/状态的 StreamMessage；服务端同时向会话全部在线参与者广播 `stream_changed`（complete=false）。`seq` 重复时覆盖该段（乱序安全）。仅流发送者可调用（其他人 1003）；流不存在 1001、已结束 1001。 可能错误码：1001 参数错误、1003 无权限。 可能触发事件：STREAM_MESSAGE_CHANGED。

StreamMessage 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.appendStreamMessage(streamId = null, delta = null, options = null, callback = callback /* ResultCallback<StreamMessage>?：实现后由主线程回调 */)

结束流式消息（IDL rev17；客户端 REST `POST /api/apps/{appkey}/messages/stream/end`）：累计文本按 start 预分配的 messageId 落库为一条普通文本消息（恰一次），随后广播 `stream_changed`（complete=true）。返回 {streamId,messageId,text,status,complete,message?}。仅流发送者可调用（1003）；空文本或已结束 1001。 可能错误码：1001 参数错误、1003 无权限。 可能触发事件：STREAM_MESSAGE_CHANGED、MESSAGES。

{streamId:string, messageId:string, text:string, status:streaming|ended, complete:bool, message?:Message} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.completeStreamMessage(streamId = null, callback = callback /* ResultCallback<StreamCompleteResult>?：实现后由主线程回调 */)

查询流式消息快照（IDL rev17；客户端 REST `GET /api/apps/{appkey}/messages/stream/{streamId}`），与 append 响应同形（StreamMessage）。仅会话参与者可见（单聊双方、群成员、聊天室在线成员；其他人 1003）；未知流 1001。 可能错误码：1001 参数错误、1003 无权限。 该操作幂等：重复调用不会产生额外副作用。

StreamMessage 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getStreamMessage(streamId = null, callback = callback /* ResultCallback<StreamMessage>?：实现后由主线程回调 */)

读取已发送消息的扩展 KV（IDL rev19；客户端 REST `GET /api/apps/{appkey}/messages/{messageId}/expansion`），返回 `{messageId, expansion}`；无扩展/已全部删除时 expansion 为空 map。仅会话参与者可读（非参与者 1003）；未知消息 1001；单聊对端用户不存在 1004、群不存在 1005、聊天室消息 1012。只读、幂等、不触发事件（写入仍由 updateMessageExpansion / removeMessageExpansion 完成）。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在、1005 群组不存在、1012 聊天室不存在。 该操作幂等：重复调用不会产生额外副作用。

{messageId:string, expansion:Record<string,string>} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getMessageExpansion(messageId = "msg_001", callback = callback /* ResultCallback<MessageExpansion>?：实现后由主线程回调 */)

本地构造合并转发内容（IDL rev19，transport=local，不做网络 IO）：把 Message[] 转换为 `{type:'combine', title, items:[{senderId,senderName?,contentType,text?,timestamp?}]}`（`CombineContent`），随后直接 `sendMessage(conversationType, targetId, content)`。items 必须 1..=100（本地 1001）；title <=64 字（缺省 ` 条聊天记录`）；条目 text 按 textMaxChars（缺省 300）截断、全部条目合计 <=16KB；构造结果序列化后仍受 `limits.messageBytes`（5KB）约束，发送时超限为 1007。 可能错误码：1001 参数错误。 该操作幂等：重复调用不会产生额外副作用。

CombineContent 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.combineMessages(messages = null, options = null, callback = callback /* ResultCallback<CombineContent>?：实现后由主线程回调 */)

会话列表：置顶优先、按 updatedAt 倒序；含未读/提及/草稿/免打扰。 可能错误码：无特定错误码（通用错误见 ErrorCode）。

Conversation[] 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getConversationList(callback = callback /* ResultCallback<List<Conversation>>：实现后由主线程回调 */)

单会话详情。 可能错误码：1001 参数错误。

Conversation 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getConversation(conversationType = ConversationType.PRIVATE, targetId = "user_001", callback = callback /* ResultCallback<Conversation>：实现后由主线程回调 */)

历史消息分页（beforeSeq 向前翻页）；limit 默认 20 上限 100。rev23：channelId 过滤超级群频道消息（仅返回该频道消息）。 可能错误码：1001 参数错误、1003 无权限。

{messages:Message[], hasMore:bool} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getHistoryMessages(conversationType = ConversationType.PRIVATE, targetId = "user_001", options = null, callback = callback /* ResultCallback<HistoryPage>：实现后由主线程回调 */)

清空会话未读（等价 read 帧 + 本地清零）。 可能错误码：无特定错误码（通用错误见 ErrorCode）。 可能触发事件：CONVERSATION。 该操作幂等：重复调用不会产生额外副作用。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

client.clearUnreadCount(conversationType = ConversationType.PRIVATE, targetId = "user_001", callback = callback /* OperationCallback?：实现后由主线程回调 */)

会话置顶/取消。 可能错误码：1001 参数错误、1003 无权限。 该操作幂等：重复调用不会产生额外副作用。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

client.setConversationToTop(conversationType = ConversationType.PRIVATE, targetId = "user_001", isTop = true, callback = callback /* OperationCallback?：实现后由主线程回调 */)

保存草稿（空串=清除）。 可能错误码：1001 参数错误、1003 无权限。 该操作幂等：重复调用不会产生额外副作用。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

client.saveTextMessageDraft(conversationType = ConversationType.PRIVATE, targetId = "user_001", draft = "明天见", callback = callback /* OperationCallback?：实现后由主线程回调 */)

读取草稿；无草稿返回空串。 可能错误码：1001 参数错误、1003 无权限。

string 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getTextMessageDraft(conversationType = ConversationType.PRIVATE, targetId = "user_001", callback = callback /* ResultCallback<String>：实现后由主线程回调 */)

清除草稿。 可能错误码：1001 参数错误、1003 无权限。 该操作幂等：重复调用不会产生额外副作用。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

client.clearTextMessageDraft(conversationType = ConversationType.PRIVATE, targetId = "user_001", callback = callback /* OperationCallback?：实现后由主线程回调 */)

会话提醒级别：0 全部 / 1 仅提及 / 2 免打扰。 可能错误码：1001 参数错误、1003 无权限。 该操作幂等：重复调用不会产生额外副作用。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

client.setConversationNotificationLevel(conversationType = ConversationType.PRIVATE, targetId = "user_001", level = NotificationLevel.MUTED, callback = callback /* OperationCallback?：实现后由主线程回调 */)

创建会话标签（tagName ≤16；单用户 ≤20 个，超出抛 1031）。 可能错误码：1001 参数错误、1031 单用户会话标签数超过上限（20）。

ConversationTag 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.createConversationTag(tagName = null, options = null, callback = callback /* ResultCallback<ConversationTag>?：实现后由主线程回调 */)

重命名会话标签。 可能错误码：1001 参数错误、1032 标签不存在。 该操作幂等：重复调用不会产生额外副作用。

ConversationTag 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.updateConversationTag(tagId = null, tagName = null, callback = callback /* ResultCallback<ConversationTag>?：实现后由主线程回调 */)

删除会话标签（同时清除标签内会话引用）。 可能错误码：1032 标签不存在。 该操作幂等：重复调用不会产生额外副作用。

void 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.deleteConversationTag(tagId = null, callback = callback /* ResultCallback<Unit>?：实现后由主线程回调 */)

获取全部会话标签（含会话数量）。 可能错误码：无特定错误码（通用错误见 ErrorCode）。 该操作幂等：重复调用不会产生额外副作用。

ConversationTag[] 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getConversationTags(callback = callback /* ResultCallback<List<ConversationTag>>?：实现后由主线程回调 */)

把会话加入标签（≤100/次，幂等；≤1000/标签，超出抛 1033）。 可能错误码：1001 参数错误、1032 标签不存在、1033 标签内会话数超过上限（1000）。 该操作幂等：重复调用不会产生额外副作用。

{added:int, existing:int, conversationCount:int} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.addConversationsToTag(tagId = null, conversations = null, callback = callback /* ResultCallback<ConversationTagMembershipResult>?：实现后由主线程回调 */)

把会话移出标签（≤100/次，幂等）。 可能错误码：1001 参数错误、1032 标签不存在。 该操作幂等：重复调用不会产生额外副作用。

{removed:int, conversationCount:int} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.removeConversationsFromTag(tagId = null, conversations = null, callback = callback /* ResultCallback<ConversationTagMembershipResult>?：实现后由主线程回调 */)

分页获取标签内会话（含置顶/未读数/最后消息时间）。 可能错误码：1032 标签不存在。 该操作幂等：重复调用不会产生额外副作用。

{total:int, items:ConversationTagConversation[]} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getConversationsFromTagByPage(tagId = null, options = null, callback = callback /* ResultCallback<ConversationTagPage>?：实现后由主线程回调 */)

查询某个会话所属的标签列表。 可能错误码：无特定错误码（通用错误见 ErrorCode）。 该操作幂等：重复调用不会产生额外副作用。

ConversationTag[] 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getTagsFromConversation(conversationType = ConversationType.PRIVATE, targetId = "user_001", callback = callback /* ResultCallback<List<ConversationTag>>?：实现后由主线程回调 */)

标签内未读汇总（消息总数 + 有未读的会话数）。 可能错误码：1032 标签不存在。 该操作幂等：重复调用不会产生额外副作用。

{unreadCount:int, unreadConversations:int, conversationCount:int} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getUnreadCountByTag(tagId = null, callback = callback /* ResultCallback<ConversationTagUnread>?：实现后由主线程回调 */)

标签内置顶/取消置顶会话（同步会话会话级置顶状态）。 可能错误码：1001 参数错误、1034 会话不存在（标签内置顶等操作要求会话已在标签内）。 该操作幂等：重复调用不会产生额外副作用。

void 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.setConversationToTopInTag(tagId = null, conversationType = ConversationType.PRIVATE, targetId = "user_001", top = null, callback = callback /* ResultCallback<Unit>?：实现后由主线程回调 */)

删除会话记录（列表项/未读/草稿/置顶），历史消息保留；同时从标签移除；幂等。 可能错误码：无特定错误码（通用错误见 ErrorCode）。 该操作幂等：重复调用不会产生额外副作用。

{removed:bool} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.deleteConversation(conversationType = ConversationType.PRIVATE, targetId = "user_001", callback = callback /* ResultCallback<Boolean>?：实现后由主线程回调 */)

查询按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰）。 可能错误码：1001 参数错误。 该操作幂等：重复调用不会产生额外副作用。

{conversationType:int, level:int} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getConversationTypeNotification(conversationType = ConversationType.PRIVATE, callback = callback /* ResultCallback<ConversationTypeNotification>?：实现后由主线程回调 */)

设置按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰）。 可能错误码：1001 参数错误。 该操作幂等：重复调用不会产生额外副作用。

{conversationType:int, level:int} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.setConversationTypeNotification(conversationType = ConversationType.PRIVATE, level = NotificationLevel.MUTED, callback = callback /* ResultCallback<ConversationTypeNotification>?：实现后由主线程回调 */)

查询用户资料。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在。

UserProfile 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getUserProfile(userId = "user_001", callback = callback /* ResultCallback<UserProfile>：实现后由主线程回调 */)

修改本人资料（name/avatarUrl）。 可能错误码：1001 参数错误、1003 无权限。

UserProfile 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.updateMyUserProfile(profile = UserProfileUpdate(name = "新昵称"), callback = callback /* ResultCallback<UserProfile>：实现后由主线程回调 */)

查询单个用户在线状态。 可能错误码：1001 参数错误、1004 用户不存在。

{userId:string, online:bool, sessionCount:uint32} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getOnlineStatus(userId = "user_001", callback = callback /* ResultCallback<UserOnlineStatus>：实现后由主线程回调 */)

批量在线状态（<=100）。 可能错误码：1001 参数错误。

{items:[{userId:string,online:bool,sessionCount:uint32}]} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getOnlineStatusBatch(userIds = ["user_001", "user_002"], callback = callback /* ResultCallback<UserOnlineStatusBatch>：实现后由主线程回调 */)

订阅用户在线状态（IDL rev20；客户端 REST `POST /api/apps/{appkey}/users/{userId}/presence/subscriptions`，userId 取自当前登录用户）。被订阅用户上线/离线/被踢/注销时通过长连接收到 `presence_changed`。订阅自己 1001；目标用户不存在/属于其它 app 1004；订阅总数上限 500（超限 1001）；幂等（重复订阅不重复入列）。成功返回变更后的完整订阅列表 `{subscribed:[...]}`。好友关系本身已默认订阅对方在线状态，无需额外调用。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在。 该操作幂等：重复调用不会产生额外副作用。

{subscribed:string[]} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.subscribePresence(userIds = ["user_001", "user_002"], callback = callback /* ResultCallback<PresenceSubscription>?：实现后由主线程回调 */)

取消订阅用户在线状态（IDL rev20；客户端 REST `POST .../presence/subscriptions` 的 `unsubscribe` 分支）。取消未订阅的用户幂等成功（不报错）；订阅自己 1001；目标用户不存在 1004。成功返回变更后的完整订阅列表 `{subscribed:[...]}`。仅停止接收该用户的实时在线状态帧，好友关系不受影响。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在。 该操作幂等：重复调用不会产生额外副作用。

{subscribed:string[]} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.unsubscribePresence(userIds = ["user_001", "user_002"], callback = callback /* ResultCallback<PresenceSubscription>?：实现后由主线程回调 */)

查询当前用户的在线状态订阅列表（IDL rev20；客户端 REST `GET /api/apps/{appkey}/users/{userId}/presence/subscriptions`）→ `{userId,subscribed:[...]}`。只读、幂等、不产生事件。 可能错误码：1001 参数错误、1003 无权限。 该操作幂等：重复调用不会产生额外副作用。

{userId:string, subscribed:string[]} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getPresenceSubscriptions(callback = callback /* ResultCallback<PresenceSubscription>?：实现后由主线程回调 */)

注册设备推送 token（IDL rev21 C23 收口；客户端 REST `POST /api/apps/{appkey}/push/tokens`，服务端 rev20 已实现，本 op 补 SDK 语义面）→ PushToken。幂等键 `(userId, platform, token)`：重复注册返回既有 tokenId 并重新置 active=true；`token` 8..=512 字符、`platform` ∈ ios|android|web|huawei|xiaomi|oppo|vivo|fcm、未知平台/长度非法 1001、每用户 20 个活跃 token 上限（超限 1001）、注销/封禁用户 1016；同一 (platform, token) 被其它用户注册时旧记录置 active=false（设备换绑）。 可能错误码：1001 参数错误、1002 Token 无效或已过期、1016 账号已被封禁。 该操作幂等：重复调用不会产生额外副作用。

PushToken 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.registerPushToken(options = null, callback = callback /* ResultCallback<PushToken>?：实现后由主线程回调 */)

注销本人设备推送 token（IDL rev21 C23；客户端 REST `DELETE /api/apps/{appkey}/push/tokens/{tokenId}`）：软删除 active=false 并保留历史供审计 → `{tokenId,userId,platform,deleted,active:false,alreadyInactive}`。非本人或不存在 1001（不泄露他人 token）；重复注销幂等成功（alreadyInactive=true）。 可能错误码：1001 参数错误、1002 Token 无效或已过期。 该操作幂等：重复调用不会产生额外副作用。

{tokenId:string, userId:string, platform:string, deleted:bool, active:bool, alreadyInactive:bool} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.unregisterPushToken(tokenId = null, callback = callback /* ResultCallback<UnregisterPushTokenResult>?：实现后由主线程回调 */)

查询本人设备推送 token（IDL rev21 C23；客户端 REST `GET /api/apps/{appkey}/push/tokens`）→ `{userId,tokens:[PushToken],total,activeTotal,platforms}`；含 active=false 历史，按 createdAt 倒序。只读、幂等、不产生事件。 可能错误码：1001 参数错误、1002 Token 无效或已过期。 该操作幂等：重复调用不会产生额外副作用。

{userId:string, tokens:PushToken[], total:uint32, activeTotal:uint32, platforms:string[]} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getPushTokens(callback = callback /* ResultCallback<PushTokenListResult>?：实现后由主线程回调 */)

搜索用户（userId/name，大小写不敏感，排除自己）。 可能错误码：1001 参数错误。

{users:[{userId:string,name:string,isFriend:bool,blacklisted:bool}], total:uint32} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.searchUsers(keyword = "ni", options = null, callback = callback /* ResultCallback<UserSearchResult>：实现后由主线程回调 */)

发起好友申请；已是好友/已有 pending → 1003；被拉黑 → 1011。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在、1011 已被对方拉黑或你已拉黑对方。 可能触发事件：FRIEND_EVENT。

FriendRequest 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.sendFriendRequest(toUserId = "user_002", message = "你好，加个好友", callback = callback /* ResultCallback<FriendRequest>：实现后由主线程回调 */)

好友申请列表（incoming/outgoing，pending/all）。 可能错误码：1001 参数错误、1003 无权限。

FriendRequest[] 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getFriendRequests(options = null, callback = callback /* ResultCallback<List<FriendRequest>>：实现后由主线程回调 */)

同意申请，双向建立好友关系。 可能错误码：1001 参数错误、1003 无权限。 可能触发事件：FRIEND_EVENT。

FriendRequest 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.acceptFriendRequest(requestId = "request_001", callback = callback /* ResultCallback<FriendRequest>：实现后由主线程回调 */)

拒绝申请。 可能错误码：1001 参数错误、1003 无权限。 可能触发事件：FRIEND_EVENT。

FriendRequest 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.rejectFriendRequest(requestId = "request_001", callback = callback /* ResultCallback<FriendRequest>：实现后由主线程回调 */)

好友列表（含备注/在线/拉黑标记）。 可能错误码：无特定错误码（通用错误见 ErrorCode）。

[{userId:string,name?:string,avatarUrl?:string,remark?:string,online?:bool,blacklisted?:bool}] 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getFriends(callback = callback /* ResultCallback<List<Friend>>：实现后由主线程回调 */)

双向删除好友。 可能错误码：1001 参数错误、1003 无权限。 该操作幂等：重复调用不会产生额外副作用。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

client.deleteFriend(friendId = "user_002", callback = callback /* OperationCallback?：实现后由主线程回调 */)

设置好友备注（<=64 字，空串清除）。 可能错误码：1001 参数错误、1003 无权限。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

client.setFriendRemark(friendId = "user_002", remark = "同事", callback = callback /* OperationCallback?：实现后由主线程回调 */)

黑名单列表。 可能错误码：无特定错误码（通用错误见 ErrorCode）。

[{userId:string,name?:string}] 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getBlacklist(callback = callback /* ResultCallback<List<BlacklistUser>>：实现后由主线程回调 */)

加入黑名单（幂等；不能拉黑自己→1001）。 可能错误码：1001 参数错误、1004 用户不存在。 该操作幂等：重复调用不会产生额外副作用。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

client.addToBlacklist(userId = "user_001", callback = callback /* OperationCallback?：实现后由主线程回调 */)

移出黑名单。 可能错误码：无特定错误码（通用错误见 ErrorCode）。 该操作幂等：重复调用不会产生额外副作用。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

client.removeFromBlacklist(userId = "user_001", callback = callback /* OperationCallback?：实现后由主线程回调 */)

创建群（groupType 缺省 normal；joinPolicy 缺省 open；maxMembers 对 super 有效）。groupId 可由调用方指定（唯一）或服务端生成。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在、1015 成员数量超出上限、1021 服务未开通。

Group 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.createGroup(name = "sample.png", memberIds = null, options = GroupOptions?(name = "sample.png"), callback = callback /* ResultCallback<Group>：实现后由主线程回调 */)

批量查询群信息（<=20）。 可能错误码：1001 参数错误。

Group[] 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getGroupsInfo(groupIds = ["group_001"], callback = callback /* ResultCallback<List<Group>>：实现后由主线程回调 */)

群成员列表（含角色/禁言）。 可能错误码：1001 参数错误、1003 无权限、1005 群组不存在、1006 未加入群组。

GroupMember[] 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getGroupMembers(groupId = "group_001", callback = callback /* ResultCallback<List<GroupMember>>：实现后由主线程回调 */)

拉人入群（群主/管理员；普通成员按配置）。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在、1005 群组不存在、1015 成员数量超出上限。

{added:string[], group:Group} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.addGroupMembers(groupId = "group_001", userIds = ["user_001", "user_002"], callback = callback /* ResultCallback<AddGroupMembersResult>：实现后由主线程回调 */)

移除成员（群主/管理员；权限检查）。 可能错误码：1001 参数错误、1003 无权限、1005 群组不存在、1006 未加入群组。

{removed:string[]} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.removeGroupMembers(groupId = "group_001", userIds = ["user_001", "user_002"], callback = callback /* ResultCallback<RemoveGroupMembersResult>：实现后由主线程回调 */)

退出群；群主需先转让。 可能错误码：1001 参数错误、1003 无权限、1005 群组不存在、1006 未加入群组。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

client.quitGroup(groupId = "group_001", callback = callback /* OperationCallback?：实现后由主线程回调 */)

修改群名（群主/管理员）。 可能错误码：1001 参数错误、1003 无权限、1005 群组不存在。

Group 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.updateGroupName(groupId = "group_001", name = "sample.png", callback = callback /* ResultCallback<Group>：实现后由主线程回调 */)

设置群公告（群主/管理员，<=500 字，空串清除）。 可能错误码：1001 参数错误、1003 无权限、1005 群组不存在。

Group 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.updateGroupNotice(groupId = "group_001", notice = "欢迎加入群聊", callback = callback /* ResultCallback<Group>：实现后由主线程回调 */)

转让群主（新群主须为成员）。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在、1005 群组不存在。

Group 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.transferGroupOwner(groupId = "group_001", newOwner = "user_001", callback = callback /* ResultCallback<Group>：实现后由主线程回调 */)

设置管理员（群主，幂等）。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在、1005 群组不存在。 该操作幂等：重复调用不会产生额外副作用。

Group 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.addGroupAdmin(groupId = "group_001", userId = "user_001", callback = callback /* ResultCallback<Group>：实现后由主线程回调 */)

取消管理员（群主）。 可能错误码：1001 参数错误、1003 无权限、1005 群组不存在。 该操作幂等：重复调用不会产生额外副作用。

Group 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.removeGroupAdmin(groupId = "group_001", userId = "user_001", callback = callback /* ResultCallback<Group>：实现后由主线程回调 */)

禁言/解禁（群主/管理员；不能禁言群主；管理员不能禁言管理员）。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在、1005 群组不存在、1006 未加入群组。

{groupId:string,userId:string,mutedUntil:uint64,group:Group} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.muteGroupMember(groupId = "group_001", userId = "user_001", mutedUntil = System.currentTimeMillis() + 3_600_000, callback = callback /* ResultCallback<MuteGroupMemberResult>：实现后由主线程回调 */)

创建超级群频道（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` 共享状态。 可能错误码：1001 参数错误、1002 Token 无效或已过期、1003 无权限、1005 群组不存在、1015 成员数量超出上限。

SupergroupChannel 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.createSupergroupChannel(params = null, callback = callback /* ResultCallback<SupergroupChannel>?：实现后由主线程回调 */)

超级群频道列表（IDL rev21 C17；客户端 REST `GET /api/apps/{appkey}/supergroup/channels?groupId=`）→ `{groupId,channels:[SupergroupChannel],total}`。仅群成员可读（否则 1003），群不存在 1005，缺 groupId 1001。 可能错误码：1001 参数错误、1002 Token 无效或已过期、1003 无权限、1005 群组不存在。 该操作幂等：重复调用不会产生额外副作用。

{groupId:string, channels:SupergroupChannel[], total:uint32} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.listSupergroupChannels(groupId = "group_001", callback = callback /* ResultCallback<SupergroupChannelListResult>?：实现后由主线程回调 */)

加入超级群频道（IDL rev21 C17；客户端 REST `POST .../supergroup/channels/{channelId}/join`，幂等）→ `{groupId,channelId,userId,joined:true,alreadyJoined}`。public 频道群成员可直接加入；private 频道需已受邀或为群主/管理员（否则 1003）。频道不存在 1005；channelId 跨群同名时可通过第二参数 `{groupId}` 消歧（未消歧 1001）；非群成员 1003。 可能错误码：1001 参数错误、1002 Token 无效或已过期、1003 无权限、1005 群组不存在。 该操作幂等：重复调用不会产生额外副作用。

{groupId:string, channelId:string, userId:string, joined:bool, alreadyJoined:bool} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.joinSupergroupChannel(channelId = null, options = SupergroupChannelOptions?(name = "sample.png"), callback = callback /* ResultCallback<JoinSupergroupChannelResult>?：实现后由主线程回调 */)

离开超级群频道（IDL rev21 C17；客户端 REST `POST .../supergroup/channels/{channelId}/leave`，幂等）→ `{groupId,channelId,userId,left:true,wasMember}`；不在频道内也返回成功（wasMember=false）。频道不存在 1005、非群成员 1003。 可能错误码：1001 参数错误、1002 Token 无效或已过期、1003 无权限、1005 群组不存在。 该操作幂等：重复调用不会产生额外副作用。

{groupId:string, channelId:string, userId:string, left:bool, wasMember:bool} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.leaveSupergroupChannel(channelId = null, options = SupergroupChannelOptions?(name = "sample.png"), callback = callback /* ResultCallback<LeaveSupergroupChannelResult>?：实现后由主线程回调 */)

把用户组绑定到频道（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。 可能错误码：1001 参数错误、1002 Token 无效或已过期、1003 无权限、1005 群组不存在。 该操作幂等：重复调用不会产生额外副作用。

{groupId:string, channelId:string, userGroupId:string, bound:bool, reverseIndexed:bool} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.bindUserGroupToChannel(channelId = null, userGroupId = null, options = SupergroupChannelOptions?(name = "sample.png"), callback = callback /* ResultCallback<BindUserGroupToChannelResult>?：实现后由主线程回调 */)

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

UserGroup 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.createUserGroup(params = null, callback = callback /* ResultCallback<UserGroup>?：实现后由主线程回调 */)

超级群用户组列表（IDL rev21 C17；客户端 REST `GET /api/apps/{appkey}/supergroup/usergroups?groupId=`）→ `{groupId,userGroups:[UserGroup],total}`；UserGroup.channelIds 为频道反向索引（rev21 修复后可用）。仅群成员可读（否则 1003），群不存在 1005，缺 groupId 1001。 可能错误码：1001 参数错误、1002 Token 无效或已过期、1003 无权限、1005 群组不存在。 该操作幂等：重复调用不会产生额外副作用。

{groupId:string, userGroups:UserGroup[], total:uint32} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.listUserGroups(groupId = "group_001", callback = callback /* ResultCallback<UserGroupListResult>?：实现后由主线程回调 */)

查询某用户所在的所有用户组（IDL rev21 C17；客户端 REST `GET .../supergroup/usergroups/by-user/{userId}`）→ `{userId,userGroups:[UserGroup],total}`。仅本人可查（userId ≠ 当前登录用户 1003）；`options.groupId` 可限定单个群；只返回「本人确实在该群」的用户组（群已删除的不返回，不虚构）。 可能错误码：1001 参数错误、1002 Token 无效或已过期、1003 无权限。 该操作幂等：重复调用不会产生额外副作用。

{userId:string, userGroups:UserGroup[], total:uint32} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getUserGroupsByUser(userId = "user_001", options = SupergroupChannelOptions?(name = "sample.png"), callback = callback /* ResultCallback<UserGroupListResult>?：实现后由主线程回调 */)

创建聊天室（客户端能力；服务端 Open API 亦可创建）。chatroomId 可指定或服务端生成。 可能错误码：1001 参数错误、1003 无权限、1015 成员数量超出上限、1021 服务未开通。

Chatroom 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.createChatroom(options = CreateChatroomOptions(name = "sample.png"), callback = callback /* ResultCallback<Chatroom>：实现后由主线程回调 */)

加入聊天室：发送 chatroom_join，收到 chatroom_joined；房内广播 member_changed。 可能错误码：1001 参数错误、1012 聊天室不存在、1013 聊天室已销毁、3001 长连接未就绪。 可能触发事件：CHATROOM_EVENT。 该操作幂等：重复调用不会产生额外副作用。

Chatroom 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.joinChatroom(chatroomId = "chatroom_001", callback = callback /* ResultCallback<Chatroom>：实现后由主线程回调 */)

离开聊天室。 可能错误码：1001 参数错误、1012 聊天室不存在、3001 长连接未就绪。 可能触发事件：CHATROOM_EVENT。 该操作幂等：重复调用不会产生额外副作用。

void / null 无业务返回值；失败时通过返回信封 code 或回调错误对象表达。

client.leaveChatroom(chatroomId = "chatroom_001", callback = callback /* OperationCallback?：实现后由主线程回调 */)

聊天室信息（含在线数）。 可能错误码：1001 参数错误、1012 聊天室不存在。

Chatroom 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getChatroomInfo(chatroomId = "chatroom_001", callback = callback /* ResultCallback<Chatroom>：实现后由主线程回调 */)

聊天室在线成员列表。 可能错误码：1001 参数错误、1012 聊天室不存在。

{members:ChatroomMember[], total:uint32} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getChatroomMembers(chatroomId = "chatroom_001", options = null, callback = callback /* ResultCallback<ChatroomMembersPage>：实现后由主线程回调 */)

系统通知历史（会话 conversationType=SYSTEM，targetId='system'）。 可能错误码：1001 参数错误。

{messages:Message[], hasMore:bool} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.getSystemMessages(options = null, callback = callback /* ResultCallback<HistoryPage>：实现后由主线程回调 */)

上传文件（<=20MB），返回可用于图片/文件/语音消息的 url。 可能错误码：1001 参数错误、1003 无权限、1007 消息体过大（上限 5KB）。

{url:string,name:string,size:uint64,mime:string,fullUrl?:string} 成功时返回上述类型；失败时返回信封 code（RcResult 泛型信封）或回调错误对象。

// 回调式 API（callback-last）：结果通过回调返回
client.uploadFile(data = bytes, name = "sample.png", mime = "image/png", callback = callback /* ResultCallback<UploadResult>：实现后由主线程回调 */)