iOS IMLib 功能列表

本页按 9 个能力域列出 103 个 IMLib 语义操作，并提供平台绑定签名与功能页入口。方法名与 IDL 语义 op 同名（规则 A）。

分组统计​

能力域操作数功能页数功能页
连接与监听72建立连接、连接监听
消息266发送消息、接收消息、消息管理、已读回执、输入状态、消息进阶
会话227历史消息、会话列表、未读数、草稿、置顶与免打扰、会话标签与分组、会话删除与类型免打扰
用户103用户资料、在线状态、在线状态订阅与推送令牌
好友与黑名单113好友列表、好友请求、黑名单
群组204创建群组、群成员、群管理、超级群频道与用户组
聊天室52加入与退出、聊天室信息
系统通知11系统通知
文件上传11文件上传

操作一览​

操作（锚点）能力域说明本平台绑定签名功能页
init连接与监听初始化 SDK（构造客户端实例）。幂等：同 appkey 重复初始化返回同一实例。static func client(options: IMPClientOptions) -> IMPClient初始化
connect连接与监听使用用户 token 建立长连接：握手→hello→离线补发→sync_done；成功后触发 CONNECTED。失败按协议重连策略重试。func connect(token: String) async -> RcResult<IMPConnectResult>建立连接
disconnect连接与监听主动断开；停止重连、清理心跳与待决请求。func disconnect() async -> RcResult<Void>建立连接
getConnectionStatus连接与监听返回 ConnectionStatus 枚举值。func getConnectionStatus() -> IMPConnectionStatus建立连接
getCurrentUserId连接与监听当前登录 userId；未登录返回空串。func getCurrentUserId() -> String连接监听
addEventListener连接与监听注册事件监听；同一 handler 重复注册只生效一次。func addEventListener(_ event: IMPEvent, listener: IMPEventListener) -> Void连接监听
removeEventListener连接与监听移除事件监听。func removeEventListener(_ event: IMPEvent, listener: IMPEventListener) -> Void连接监听
sendMessage消息发送任意类型消息。优先走长连接；连接不可用（SUSPEND/DISCONNECTED）时按 SDK_NO_CONNECTION 失败并保留本地待发队列（可选实现）。rev23：options.channelId 用于超级群频道消息（conversationType=10），仅频道成员接收；消息模型带 channelId。func sendMessage(conversationType: IMPConversationType, targetId: String, content: IMPMessageContent, options: IMPSendOptions?) async -> RcResult<IMPMessage>发送消息
sendTextMessage消息发送文本消息；内部等价 sendMessage(content={type:'text',text,mentionedInfo?,quote?})。func sendTextMessage(conversationType: IMPConversationType, targetId: String, text: String, options: IMPTextSendOptions?) async -> RcResult<IMPMessage>发送消息
sendImageMessage消息发送图片消息；url 由 uploadFile 或业务方上传得到。func sendImageMessage(conversationType: IMPConversationType, targetId: String, content: IMPImageContent, options: IMPSendOptions?) async -> RcResult<IMPMessage>发送消息
sendFileMessage消息发送文件消息。func sendFileMessage(conversationType: IMPConversationType, targetId: String, content: IMPFileContent, options: IMPSendOptions?) async -> RcResult<IMPMessage>发送消息
sendVoiceMessage消息发送语音消息；duration 秒 1..300。func sendVoiceMessage(conversationType: IMPConversationType, targetId: String, content: IMPVoiceContent, options: IMPSendOptions?) async -> RcResult<IMPMessage>发送消息
sendLocationMessage消息发送位置消息；lat/lng 范围校验。func sendLocationMessage(conversationType: IMPConversationType, targetId: String, content: IMPLocationContent, options: IMPSendOptions?) async -> RcResult<IMPMessage>发送消息
sendTypingStatus消息发送正在输入状态；不持久化；对端触发 TYPING 事件。func sendTypingStatus(conversationType: IMPConversationType, targetId: String, typing: Bool) async -> RcResult<Void>输入状态
recallMessage消息撤回消息（仅发送者、撤回时限内）。成功后本地与对端收到 MESSAGE_RECALLED。func recallMessage(messageId: String) async -> RcResult<IMPMessage>消息管理
sendReadReceipt消息上报已读回执；服务端记录唯一读者并推送给消息发送者。func sendReadReceipt(conversationType: IMPConversationType, targetId: String, messageIds: [String]) async -> RcResult<IMPSendReadReceiptResult>已读回执
getMessageReadCount消息查询消息已读人数。func getMessageReadCount(messageId: String) async -> RcResult<IMPMessageReadCount>已读回执
getMessageReadUsers消息查询已读用户明细（分页）。func getMessageReadUsers(messageId: String, options: IMPPageOptions?) async -> RcResult<IMPMessageReadUsers>已读回执
getMessageReadDetail消息查询单条消息的已读详情：已读/未读名单 + 具体读取时间（分页；filter=all|read|unread，默认 all）。func getMessageReadDetail(messageId: String, options: IMPPageOptions?) async -> RcResult<IMPMessageReadDetail>—
searchMessages消息在当前用户全部会话中搜索文本消息（倒序）。func searchMessages(options: IMPSearchMessagesOptions) async -> RcResult<IMPMessageSearchResult>消息管理
getConversationList会话会话列表：置顶优先、按 updatedAt 倒序；含未读/提及/草稿/免打扰。func getConversationList() async -> RcResult<[IMPConversation]>会话列表
getConversation会话单会话详情。func getConversation(conversationType: IMPConversationType, targetId: String) async -> RcResult<IMPConversation>会话列表
getHistoryMessages会话历史消息分页（beforeSeq 向前翻页）；limit 默认 20 上限 100。rev23：channelId 过滤超级群频道消息（仅返回该频道消息）。func getHistoryMessages(conversationType: IMPConversationType, targetId: String, options: IMPHistoryOptions?) async -> RcResult<IMPHistoryPage>历史消息
clearUnreadCount会话清空会话未读（等价 read 帧 + 本地清零）。func clearUnreadCount(conversationType: IMPConversationType, targetId: String) async -> RcResult<Void>未读数
setConversationToTop会话会话置顶/取消。func setConversationToTop(conversationType: IMPConversationType, targetId: String, isTop: Bool) async -> RcResult<Void>置顶与免打扰
saveTextMessageDraft会话保存草稿（空串=清除）。func saveTextMessageDraft(conversationType: IMPConversationType, targetId: String, draft: String) async -> RcResult<Void>草稿
getTextMessageDraft会话读取草稿；无草稿返回空串。func getTextMessageDraft(conversationType: IMPConversationType, targetId: String) async -> RcResult<String>草稿
clearTextMessageDraft会话清除草稿。func clearTextMessageDraft(conversationType: IMPConversationType, targetId: String) async -> RcResult<Void>草稿
setConversationNotificationLevel会话会话提醒级别：0 全部 / 1 仅提及 / 2 免打扰。func setConversationNotificationLevel(conversationType: IMPConversationType, targetId: String, level: IMPNotificationLevel) async -> RcResult<Void>置顶与免打扰
getUserProfile用户查询用户资料。func getUserProfile(userId: String) async -> RcResult<IMPUserProfile>用户资料
updateMyUserProfile用户修改本人资料（name/avatarUrl）。func updateMyUserProfile(profile: IMPUserProfileUpdate) async -> RcResult<IMPUserProfile>用户资料
getOnlineStatus用户查询单个用户在线状态。func getOnlineStatus(userId: String) async -> RcResult<IMPUserOnlineStatus>在线状态
getOnlineStatusBatch用户批量在线状态（<=100）。func getOnlineStatusBatch(userIds: [String]) async -> RcResult<IMPUserOnlineStatusBatch>在线状态
searchUsers好友与黑名单搜索用户（userId/name，大小写不敏感，排除自己）。func searchUsers(keyword: String, options: IMPPageOptions?) async -> RcResult<IMPUserSearchResult>好友列表
sendFriendRequest好友与黑名单发起好友申请；已是好友/已有 pending → 1003；被拉黑 → 1011。func sendFriendRequest(toUserId: String, message: String?) async -> RcResult<IMPFriendRequest>好友请求
getFriendRequests好友与黑名单好友申请列表（incoming/outgoing，pending/all）。func getFriendRequests(options: IMPFriendRequestQuery?) async -> RcResult<[IMPFriendRequest]>好友请求
acceptFriendRequest好友与黑名单同意申请，双向建立好友关系。func acceptFriendRequest(requestId: String) async -> RcResult<IMPFriendRequest>好友请求
rejectFriendRequest好友与黑名单拒绝申请。func rejectFriendRequest(requestId: String) async -> RcResult<IMPFriendRequest>好友请求
getFriends好友与黑名单好友列表（含备注/在线/拉黑标记）。func getFriends() async -> RcResult<[IMPFriend]>好友列表
deleteFriend好友与黑名单双向删除好友。func deleteFriend(friendId: String) async -> RcResult<Void>好友列表
setFriendRemark好友与黑名单设置好友备注（<=64 字，空串清除）。func setFriendRemark(friendId: String, remark: String) async -> RcResult<Void>好友列表
getBlacklist好友与黑名单黑名单列表。func getBlacklist() async -> RcResult<[IMPBlacklistEntry]>黑名单
addToBlacklist好友与黑名单加入黑名单（幂等；不能拉黑自己→1001）。func addToBlacklist(userId: String) async -> RcResult<Void>黑名单
removeFromBlacklist好友与黑名单移出黑名单。func removeFromBlacklist(userId: String) async -> RcResult<Void>黑名单
createGroup群组创建群（groupType 缺省 normal；joinPolicy 缺省 open；maxMembers 对 super 有效）。groupId 可由调用方指定（唯一）或服务端生成。func createGroup(_ options: IMPCreateGroupOptions) async -> RcResult<IMPGroup>创建群组
getGroupsInfo群组批量查询群信息（<=20）。func getGroupsInfo(groupIds: [String]) async -> RcResult<[IMPGroup]>创建群组
getGroupMembers群组群成员列表（含角色/禁言）。func getGroupMembers(groupId: String) async -> RcResult<[IMPGroupMember]>群成员
addGroupMembers群组拉人入群（群主/管理员；普通成员按配置）。func addGroupMembers(groupId: String, userIds: [String]) async -> RcResult<IMPAddGroupMembersResult>群成员
removeGroupMembers群组移除成员（群主/管理员；权限检查）。func removeGroupMembers(groupId: String, userIds: [String]) async -> RcResult<IMPRemoveGroupMembersResult>群成员
quitGroup群组退出群；群主需先转让。func quitGroup(groupId: String) async -> RcResult<Void>群成员
updateGroupName群组修改群名（群主/管理员）。func updateGroupName(groupId: String, name: String) async -> RcResult<IMPGroup>群管理
updateGroupNotice群组设置群公告（群主/管理员，<=500 字，空串清除）。func updateGroupNotice(groupId: String, notice: String) async -> RcResult<IMPGroup>群管理
transferGroupOwner群组转让群主（新群主须为成员）。func transferGroupOwner(groupId: String, newOwner: String) async -> RcResult<IMPGroup>群管理
addGroupAdmin群组设置管理员（群主，幂等）。func addGroupAdmin(groupId: String, userId: String) async -> RcResult<IMPGroup>群管理
removeGroupAdmin群组取消管理员（群主）。func removeGroupAdmin(groupId: String, userId: String) async -> RcResult<IMPGroup>群管理
muteGroupMember群组禁言/解禁（群主/管理员；不能禁言群主；管理员不能禁言管理员）。func muteGroupMember(groupId: String, userId: String, mutedUntil: UInt64) async -> RcResult<IMPMuteGroupMemberResult>群管理
createChatroom聊天室创建聊天室（客户端能力；服务端 Open API 亦可创建）。chatroomId 可指定或服务端生成。func createChatroom(options: IMPCreateChatroomOptions) async -> RcResult<IMPChatroom>加入与退出
joinChatroom聊天室加入聊天室：发送 chatroom_join，收到 chatroom_joined；房内广播 member_changed。func joinChatroom(chatroomId: String) async -> RcResult<IMPChatroom>加入与退出
leaveChatroom聊天室离开聊天室。func leaveChatroom(chatroomId: String) async -> RcResult<Void>加入与退出
getChatroomInfo聊天室聊天室信息（含在线数）。func getChatroomInfo(chatroomId: String) async -> RcResult<IMPChatroom>聊天室信息
getChatroomMembers聊天室聊天室在线成员列表。func getChatroomMembers(chatroomId: String, options: IMPPageOptions?) async -> RcResult<IMPChatroomMembersPage>聊天室信息
getSystemMessages系统通知系统通知历史（会话 conversationType=SYSTEM，targetId='system'）。func getSystemMessages(options: IMPHistoryOptions?) async -> RcResult<IMPHistoryPage>系统通知
uploadFile文件上传上传文件（<=20MB），返回可用于图片/文件/语音消息的 url。func uploadFile(data: Data, name: String, mime: String?) async -> RcResult<IMPUploadResult>文件上传
updateMessageExpansion消息更新已发送消息的扩展 KV（合并语义）。仅单聊/群聊/超级群支持，且消息须在发送时开启可扩展；单次 ≤20 对、单条 ≤300 对，key 1-32 字符 [A-Za-z0-9+=_-]、value ≤4096。func updateMessageExpansion(messageId: String, expansion: [String: String]) async -> RcResult<IMPExpansion>消息进阶
removeMessageExpansion消息删除消息扩展 KV（按 key）。语义与融云 removeMessageExpansion 对齐：消息须可扩展，删除不存在的 key 不报错。func removeMessageExpansion(messageId: String, keys: [String]) async -> RcResult<IMPExpansion>消息进阶
addMessageReaction消息为指定消息添加回应（reactionId 由业务定义，1-16 字符；同一用户对同一消息同一 reactionId 重复添加视为幂等）。单条消息最多 50 种回应、每种回应最多 100 个用户。func addMessageReaction(_ param: IMPUpdateMessageReactionParam) async -> RcResult<IMPMessageReaction>消息进阶
removeMessageReaction消息移除自己对指定消息的回应；reactionId 须与添加时一致，未添加过时返回成功（removed=false）。func removeMessageReaction(_ param: IMPUpdateMessageReactionParam) async -> RcResult<IMPReactionRemoval>消息进阶
batchGetMessageReactionSummaries消息批量查询消息回应摘要（1-100 个 messageId）。返回按 messageId 分组：每个回应含总数、当前用户是否已回应、最近参与用户（最多 10 个）；不存在回应的消息返回空数组。func batchGetMessageReactionSummaries(_ param: IMPMessageReactionSummaryQuery) async -> RcResult<[String: [IMPMessageReactionSummary]]>消息进阶
getMessageReactions消息分页查询指定消息的回应列表（count 1-50，默认 20；pageToken 不透明，空串表示第一页）。func getMessageReactions(_ param: IMPGetMessageReactionsParam) async -> RcResult<IMPMessageReactionPage>消息进阶
getMessageReactionUsers消息分页查询某个回应的参与用户（count 1-50，默认 20；pageToken 不透明）。func getMessageReactionUsers(_ param: IMPGetMessageReactionUsersParam) async -> RcResult<IMPMessageReactionUserPage>消息进阶
createConversationTag会话创建会话标签（tagName ≤16；单用户 ≤20 个，超出抛 1031）。func createConversationTag(_ param: IMPCreateConversationTagParam) async -> RcResult<IMPConversationTag>会话标签与分组
updateConversationTag会话重命名会话标签。func updateConversationTag(_ param: IMPUpdateConversationTagParam) async -> RcResult<IMPConversationTag>会话标签与分组
deleteConversationTag会话删除会话标签（同时清除标签内会话引用）。func deleteConversationTag(tagId: String) async -> RcResult<Void>会话标签与分组
getConversationTags会话获取全部会话标签（含会话数量）。func getConversationTags() async -> RcResult<[IMPConversationTag]>会话标签与分组
addConversationsToTag会话把会话加入标签（≤100/次，幂等；≤1000/标签，超出抛 1033）。func addConversationsToTag(_ param: IMPTagConversationsParam) async -> RcResult<IMPConversationTagMembershipResult>会话标签与分组
removeConversationsFromTag会话把会话移出标签（≤100/次，幂等）。func removeConversationsFromTag(_ param: IMPTagConversationsParam) async -> RcResult<IMPConversationTagMembershipResult>会话标签与分组
getConversationsFromTagByPage会话分页获取标签内会话（含置顶/未读数/最后消息时间）。func getConversationsFromTagByPage(_ param: IMPTagConversationsPageParam) async -> RcResult<IMPConversationTagPage>会话标签与分组
getTagsFromConversation会话查询某个会话所属的标签列表。func getTagsFromConversation(conversationType: Int, targetId: String) async -> RcResult<[IMPConversationTag]>会话标签与分组
getUnreadCountByTag会话标签内未读汇总（消息总数 + 有未读的会话数）。func getUnreadCountByTag(tagId: String) async -> RcResult<IMPConversationTagUnread>会话标签与分组
setConversationToTopInTag会话标签内置顶/取消置顶会话（同步会话会话级置顶状态）。func setConversationToTopInTag(_ param: IMPTagTopParam) async -> RcResult<Void>会话标签与分组
deleteConversation会话删除会话记录（列表项/未读/草稿/置顶），历史消息保留；同时从标签移除；幂等。func deleteConversation(conversationType: Int, targetId: String) async -> RcResult<Bool>会话删除与类型免打扰
getConversationTypeNotification会话查询按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰）。func getConversationTypeNotification(conversationType: Int) async -> RcResult<IMPConversationTypeNotification>会话删除与类型免打扰
setConversationTypeNotification会话设置按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰）。func setConversationTypeNotification(conversationType: Int, level: Int) async -> RcResult<IMPConversationTypeNotification>会话删除与类型免打扰
startStreamMessage消息开始一条流式消息（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）。func startStreamMessage(_ param: IMPStartStreamMessageParam) async -> RcResult<IMPStreamMessage>消息进阶
appendStreamMessage消息追加一个流式增量（IDL rev17；客户端 REST `POST /api/apps/{appkey}/messages/stream/append`），返回累计文本/分段/状态的 StreamMessage；服务端同时向会话全部在线参与者广播 `stream_changed`（complete=false）。`seq` 重复时覆盖该段（乱序安全）。仅流发送者可调用（其他人 1003）；流不存在 1001、已结束 1001。func appendStreamMessage(streamId: String, delta: String, seq: UInt32?) async -> RcResult<IMPStreamMessage>消息进阶
completeStreamMessage消息结束流式消息（IDL rev17；客户端 REST `POST /api/apps/{appkey}/messages/stream/end`）：累计文本按 start 预分配的 messageId 落库为一条普通文本消息（恰一次），随后广播 `stream_changed`（complete=true）。返回 {streamId,messageId,text,status,complete,message?}。仅流发送者可调用（1003）；空文本或已结束 1001。func completeStreamMessage(streamId: String) async -> RcResult<IMPStreamCompleteResult>消息进阶
getStreamMessage消息查询流式消息快照（IDL rev17；客户端 REST `GET /api/apps/{appkey}/messages/stream/{streamId}`），与 append 响应同形（StreamMessage）。仅会话参与者可见（单聊双方、群成员、聊天室在线成员；其他人 1003）；未知流 1001。func getStreamMessage(streamId: String) async -> RcResult<IMPStreamMessage>消息进阶
getMessageExpansion消息读取已发送消息的扩展 KV（IDL rev19；客户端 REST `GET /api/apps/{appkey}/messages/{messageId}/expansion`），返回 `{messageId, expansion}`；无扩展/已全部删除时 expansion 为空 map。仅会话参与者可读（非参与者 1003）；未知消息 1001；单聊对端用户不存在 1004、群不存在 1005、聊天室消息 1012。只读、幂等、不触发事件（写入仍由 updateMessageExpansion / removeMessageExpansion 完成）。func getMessageExpansion(messageId: String) async -> RcResult<IMPMessageExpansion>消息进阶
combineMessages消息本地构造合并转发内容（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 字（缺省 `<n> 条聊天记录`）；条目 text 按 textMaxChars（缺省 300）截断、全部条目合计 <=16KB；构造结果序列化后仍受 `limits.messageBytes`（5KB）约束，发送时超限为 1007。func combineMessages(_ messages: [IMPMessage], options: IMPCombineMessagesOptions?) -> RcResult<IMPCombineContent>消息进阶
subscribePresence用户订阅用户在线状态（IDL rev20；客户端 REST `POST /api/apps/{appkey}/users/{userId}/presence/subscriptions`，userId 取自当前登录用户）。被订阅用户上线/离线/被踢/注销时通过长连接收到 `presence_changed`。订阅自己 1001；目标用户不存在/属于其它 app 1004；订阅总数上限 500（超限 1001）；幂等（重复订阅不重复入列）。成功返回变更后的完整订阅列表 `{subscribed:[...]}`。好友关系本身已默认订阅对方在线状态，无需额外调用。func subscribePresence(userIds: [String]) async -> RcResult<IMPPresenceSubscription>在线状态订阅与推送令牌
unsubscribePresence用户取消订阅用户在线状态（IDL rev20；客户端 REST `POST .../presence/subscriptions` 的 `unsubscribe` 分支）。取消未订阅的用户幂等成功（不报错）；订阅自己 1001；目标用户不存在 1004。成功返回变更后的完整订阅列表 `{subscribed:[...]}`。仅停止接收该用户的实时在线状态帧，好友关系不受影响。func unsubscribePresence(userIds: [String]) async -> RcResult<IMPPresenceSubscription>在线状态订阅与推送令牌
getPresenceSubscriptions用户查询当前用户的在线状态订阅列表（IDL rev20；客户端 REST `GET /api/apps/{appkey}/users/{userId}/presence/subscriptions`）→ `{userId,subscribed:[...]}`。只读、幂等、不产生事件。func getPresenceSubscriptions() async -> RcResult<IMPPresenceSubscription>在线状态订阅与推送令牌
registerPushToken用户注册设备推送 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（设备换绑）。func registerPushToken(options: IMPRegisterPushTokenOptions) async -> RcResult<IMPPushToken>在线状态订阅与推送令牌
unregisterPushToken用户注销本人设备推送 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）。func unregisterPushToken(tokenId: String) async -> RcResult<IMPUnregisterPushTokenResult>在线状态订阅与推送令牌
getPushTokens用户查询本人设备推送 token（IDL rev21 C23；客户端 REST `GET /api/apps/{appkey}/push/tokens`）→ `{userId,tokens:[PushToken],total,activeTotal,platforms}`；含 active=false 历史，按 createdAt 倒序。只读、幂等、不产生事件。func getPushTokens() async -> RcResult<IMPPushTokenListResult>在线状态订阅与推送令牌
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` 共享状态。func createSupergroupChannel(params: IMPCreateSupergroupChannelParams) async -> RcResult<IMPSupergroupChannel>超级群频道与用户组
listSupergroupChannels群组超级群频道列表（IDL rev21 C17；客户端 REST `GET /api/apps/{appkey}/supergroup/channels?groupId=`）→ `{groupId,channels:[SupergroupChannel],total}`。仅群成员可读（否则 1003），群不存在 1005，缺 groupId 1001。func listSupergroupChannels(groupId: String) async -> RcResult<IMPSupergroupChannelListResult>超级群频道与用户组
joinSupergroupChannel群组加入超级群频道（IDL rev21 C17；客户端 REST `POST .../supergroup/channels/{channelId}/join`，幂等）→ `{groupId,channelId,userId,joined:true,alreadyJoined}`。public 频道群成员可直接加入；private 频道需已受邀或为群主/管理员（否则 1003）。频道不存在 1005；channelId 跨群同名时可通过第二参数 `{groupId}` 消歧（未消歧 1001）；非群成员 1003。func joinSupergroupChannel(channelId: String, options: IMPSupergroupChannelOptions?) async -> RcResult<IMPJoinSupergroupChannelResult>超级群频道与用户组
leaveSupergroupChannel群组离开超级群频道（IDL rev21 C17；客户端 REST `POST .../supergroup/channels/{channelId}/leave`，幂等）→ `{groupId,channelId,userId,left:true,wasMember}`；不在频道内也返回成功（wasMember=false）。频道不存在 1005、非群成员 1003。func leaveSupergroupChannel(channelId: String, options: IMPSupergroupChannelOptions?) async -> RcResult<IMPLeaveSupergroupChannelResult>超级群频道与用户组
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。func bindUserGroupToChannel(channelId: String, userGroupId: String, options: IMPSupergroupChannelOptions?) async -> RcResult<IMPBindUserGroupToChannelResult>超级群频道与用户组
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.*` 共享状态。func createUserGroup(params: IMPCreateUserGroupParams) async -> RcResult<IMPUserGroup>超级群频道与用户组
listUserGroups群组超级群用户组列表（IDL rev21 C17；客户端 REST `GET /api/apps/{appkey}/supergroup/usergroups?groupId=`）→ `{groupId,userGroups:[UserGroup],total}`；UserGroup.channelIds 为频道反向索引（rev21 修复后可用）。仅群成员可读（否则 1003），群不存在 1005，缺 groupId 1001。func listUserGroups(groupId: String) async -> RcResult<IMPUserGroupListResult>超级群频道与用户组
getUserGroupsByUser群组查询某用户所在的所有用户组（IDL rev21 C17；客户端 REST `GET .../supergroup/usergroups/by-user/{userId}`）→ `{userId,userGroups:[UserGroup],total}`。仅本人可查（userId ≠ 当前登录用户 1003）；`options.groupId` 可限定单个群；只返回「本人确实在该群」的用户组（群已删除的不返回，不虚构）。func getUserGroupsByUser(userId: String, options: IMPSupergroupChannelOptions?) async -> RcResult<IMPUserGroupListResult>超级群频道与用户组

操作详情索引​

连接与监听（7）​

  • init · 初始化 SDK（构造客户端实例）。幂等：同 appkey 重复初始化返回同一实例。
  • connect · 使用用户 token 建立长连接：握手→hello→离线补发→sync_done；成功后触发 CONNECTED。失败按协议重连策略重试。
  • disconnect · 主动断开；停止重连、清理心跳与待决请求。
  • getConnectionStatus · 返回 ConnectionStatus 枚举值。
  • getCurrentUserId · 当前登录 userId；未登录返回空串。
  • addEventListener · 注册事件监听；同一 handler 重复注册只生效一次。
  • removeEventListener · 移除事件监听。

消息（26）​

  • sendMessage · 发送任意类型消息。优先走长连接；连接不可用（SUSPEND/DISCONNECTED）时按 SDK_NO_CONNECTION 失败并保留本地待发队列（可选实现）。rev23：options.channelId 用于超级群频道消息（conversationType=10），仅频道成员接收；消息模型带 channelId。
  • sendTextMessage · 发送文本消息；内部等价 sendMessage(content={type:'text',text,mentionedInfo?,quote?})。
  • sendImageMessage · 发送图片消息；url 由 uploadFile 或业务方上传得到。
  • sendFileMessage · 发送文件消息。
  • sendVoiceMessage · 发送语音消息；duration 秒 1..300。
  • sendLocationMessage · 发送位置消息；lat/lng 范围校验。
  • sendTypingStatus · 发送正在输入状态；不持久化；对端触发 TYPING 事件。
  • recallMessage · 撤回消息（仅发送者、撤回时限内）。成功后本地与对端收到 MESSAGE_RECALLED。
  • sendReadReceipt · 上报已读回执；服务端记录唯一读者并推送给消息发送者。
  • getMessageReadCount · 查询消息已读人数。
  • getMessageReadUsers · 查询已读用户明细（分页）。
  • getMessageReadDetail · 查询单条消息的已读详情：已读/未读名单 + 具体读取时间（分页；filter=all|read|unread，默认 all）。
  • searchMessages · 在当前用户全部会话中搜索文本消息（倒序）。
  • updateMessageExpansion · 更新已发送消息的扩展 KV（合并语义）。仅单聊/群聊/超级群支持，且消息须在发送时开启可扩展；单次 ≤20 对、单条 ≤300 对，key 1-32 字符 [A-Za-z0-9+=_-]、value ≤4096。
  • removeMessageExpansion · 删除消息扩展 KV（按 key）。语义与融云 removeMessageExpansion 对齐：消息须可扩展，删除不存在的 key 不报错。
  • addMessageReaction · 为指定消息添加回应（reactionId 由业务定义，1-16 字符；同一用户对同一消息同一 reactionId 重复添加视为幂等）。单条消息最多 50 种回应、每种回应最多 100 个用户。
  • removeMessageReaction · 移除自己对指定消息的回应；reactionId 须与添加时一致，未添加过时返回成功（removed=false）。
  • batchGetMessageReactionSummaries · 批量查询消息回应摘要（1-100 个 messageId）。返回按 messageId 分组：每个回应含总数、当前用户是否已回应、最近参与用户（最多 10 个）；不存在回应的消息返回空数组。
  • getMessageReactions · 分页查询指定消息的回应列表（count 1-50，默认 20；pageToken 不透明，空串表示第一页）。
  • getMessageReactionUsers · 分页查询某个回应的参与用户（count 1-50，默认 20；pageToken 不透明）。
  • startStreamMessage · 开始一条流式消息（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）。
  • appendStreamMessage · 追加一个流式增量（IDL rev17；客户端 REST `POST /api/apps/{appkey}/messages/stream/append`），返回累计文本/分段/状态的 StreamMessage；服务端同时向会话全部在线参与者广播 `stream_changed`（complete=false）。`seq` 重复时覆盖该段（乱序安全）。仅流发送者可调用（其他人 1003）；流不存在 1001、已结束 1001。
  • completeStreamMessage · 结束流式消息（IDL rev17；客户端 REST `POST /api/apps/{appkey}/messages/stream/end`）：累计文本按 start 预分配的 messageId 落库为一条普通文本消息（恰一次），随后广播 `stream_changed`（complete=true）。返回 {streamId,messageId,text,status,complete,message?}。仅流发送者可调用（1003）；空文本或已结束 1001。
  • getStreamMessage · 查询流式消息快照（IDL rev17；客户端 REST `GET /api/apps/{appkey}/messages/stream/{streamId}`），与 append 响应同形（StreamMessage）。仅会话参与者可见（单聊双方、群成员、聊天室在线成员；其他人 1003）；未知流 1001。
  • getMessageExpansion · 读取已发送消息的扩展 KV（IDL rev19；客户端 REST `GET /api/apps/{appkey}/messages/{messageId}/expansion`），返回 `{messageId, expansion}`；无扩展/已全部删除时 expansion 为空 map。仅会话参与者可读（非参与者 1003）；未知消息 1001；单聊对端用户不存在 1004、群不存在 1005、聊天室消息 1012。只读、幂等、不触发事件（写入仍由 updateMessageExpansion / removeMessageExpansion 完成）。
  • combineMessages · 本地构造合并转发内容（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 字（缺省 `<n> 条聊天记录`）；条目 text 按 textMaxChars（缺省 300）截断、全部条目合计 <=16KB；构造结果序列化后仍受 `limits.messageBytes`（5KB）约束，发送时超限为 1007。

会话（22）​

用户（10）​

  • getUserProfile · 查询用户资料。
  • updateMyUserProfile · 修改本人资料（name/avatarUrl）。
  • getOnlineStatus · 查询单个用户在线状态。
  • getOnlineStatusBatch · 批量在线状态（<=100）。
  • subscribePresence · 订阅用户在线状态（IDL rev20；客户端 REST `POST /api/apps/{appkey}/users/{userId}/presence/subscriptions`，userId 取自当前登录用户）。被订阅用户上线/离线/被踢/注销时通过长连接收到 `presence_changed`。订阅自己 1001；目标用户不存在/属于其它 app 1004；订阅总数上限 500（超限 1001）；幂等（重复订阅不重复入列）。成功返回变更后的完整订阅列表 `{subscribed:[...]}`。好友关系本身已默认订阅对方在线状态，无需额外调用。
  • unsubscribePresence · 取消订阅用户在线状态（IDL rev20；客户端 REST `POST .../presence/subscriptions` 的 `unsubscribe` 分支）。取消未订阅的用户幂等成功（不报错）；订阅自己 1001；目标用户不存在 1004。成功返回变更后的完整订阅列表 `{subscribed:[...]}`。仅停止接收该用户的实时在线状态帧，好友关系不受影响。
  • getPresenceSubscriptions · 查询当前用户的在线状态订阅列表（IDL rev20；客户端 REST `GET /api/apps/{appkey}/users/{userId}/presence/subscriptions`）→ `{userId,subscribed:[...]}`。只读、幂等、不产生事件。
  • registerPushToken · 注册设备推送 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（设备换绑）。
  • unregisterPushToken · 注销本人设备推送 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）。
  • getPushTokens · 查询本人设备推送 token（IDL rev21 C23；客户端 REST `GET /api/apps/{appkey}/push/tokens`）→ `{userId,tokens:[PushToken],total,activeTotal,platforms}`；含 active=false 历史，按 createdAt 倒序。只读、幂等、不产生事件。

好友与黑名单（11）​

群组（20）​

  • createGroup · 创建群（groupType 缺省 normal；joinPolicy 缺省 open；maxMembers 对 super 有效）。groupId 可由调用方指定（唯一）或服务端生成。
  • getGroupsInfo · 批量查询群信息（<=20）。
  • getGroupMembers · 群成员列表（含角色/禁言）。
  • addGroupMembers · 拉人入群（群主/管理员；普通成员按配置）。
  • removeGroupMembers · 移除成员（群主/管理员；权限检查）。
  • quitGroup · 退出群；群主需先转让。
  • updateGroupName · 修改群名（群主/管理员）。
  • updateGroupNotice · 设置群公告（群主/管理员，<=500 字，空串清除）。
  • transferGroupOwner · 转让群主（新群主须为成员）。
  • addGroupAdmin · 设置管理员（群主，幂等）。
  • removeGroupAdmin · 取消管理员（群主）。
  • muteGroupMember · 禁言/解禁（群主/管理员；不能禁言群主；管理员不能禁言管理员）。
  • 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` 共享状态。
  • listSupergroupChannels · 超级群频道列表（IDL rev21 C17；客户端 REST `GET /api/apps/{appkey}/supergroup/channels?groupId=`）→ `{groupId,channels:[SupergroupChannel],total}`。仅群成员可读（否则 1003），群不存在 1005，缺 groupId 1001。
  • joinSupergroupChannel · 加入超级群频道（IDL rev21 C17；客户端 REST `POST .../supergroup/channels/{channelId}/join`，幂等）→ `{groupId,channelId,userId,joined:true,alreadyJoined}`。public 频道群成员可直接加入；private 频道需已受邀或为群主/管理员（否则 1003）。频道不存在 1005；channelId 跨群同名时可通过第二参数 `{groupId}` 消歧（未消歧 1001）；非群成员 1003。
  • leaveSupergroupChannel · 离开超级群频道（IDL rev21 C17；客户端 REST `POST .../supergroup/channels/{channelId}/leave`，幂等）→ `{groupId,channelId,userId,left:true,wasMember}`；不在频道内也返回成功（wasMember=false）。频道不存在 1005、非群成员 1003。
  • 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。
  • 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.*` 共享状态。
  • listUserGroups · 超级群用户组列表（IDL rev21 C17；客户端 REST `GET /api/apps/{appkey}/supergroup/usergroups?groupId=`）→ `{groupId,userGroups:[UserGroup],total}`；UserGroup.channelIds 为频道反向索引（rev21 修复后可用）。仅群成员可读（否则 1003），群不存在 1005，缺 groupId 1001。
  • getUserGroupsByUser · 查询某用户所在的所有用户组（IDL rev21 C17；客户端 REST `GET .../supergroup/usergroups/by-user/{userId}`）→ `{userId,userGroups:[UserGroup],total}`。仅本人可查（userId ≠ 当前登录用户 1003）；`options.groupId` 可限定单个群；只返回「本人确实在该群」的用户组（群已删除的不返回，不虚构）。

聊天室（5）​

  • createChatroom · 创建聊天室（客户端能力；服务端 Open API 亦可创建）。chatroomId 可指定或服务端生成。
  • joinChatroom · 加入聊天室：发送 chatroom_join，收到 chatroom_joined；房内广播 member_changed。
  • leaveChatroom · 离开聊天室。
  • getChatroomInfo · 聊天室信息（含在线数）。
  • getChatroomMembers · 聊天室在线成员列表。

系统通知（1）​

  • getSystemMessages · 系统通知历史（会话 conversationType=SYSTEM，targetId='system'）。

文件上传（1）​

  • uploadFile · 上传文件（<=20MB），返回可用于图片/文件/语音消息的 url。