HarmonyOS IMLib 功能列表
本页按 9 个能力域列出 103 个 IMLib 语义操作，并提供平台绑定签名与功能页入口。方法名与 IDL 语义 op 同名（规则 A）。
契约预留
本平台为 reserved：签名来自已冻结绑定，页面中的方法尚未实现。
分组统计
| 能力域 | 操作数 | 功能页数 | 功能页 |
|---|---|---|---|
| 连接与监听 | 7 | 2 | 建立连接、连接监听 |
| 消息 | 26 | 6 | 发送消息、接收消息、消息管理、已读回执、输入状态、消息进阶 |
| 会话 | 22 | 7 | 历史消息、会话列表、未读数、草稿、置顶与免打扰、会话标签与分组、会话删除与类型免打扰 |
| 用户 | 10 | 3 | 用户资料、在线状态、在线状态订阅与推送令牌 |
| 好友与黑名单 | 11 | 3 | 好友列表、好友请求、黑名单 |
| 群组 | 20 | 4 | 创建群组、群成员、群管理、超级群频道与用户组 |
| 聊天室 | 5 | 2 | 加入与退出、聊天室信息 |
| 系统通知 | 1 | 1 | 系统通知 |
| 文件上传 | 1 | 1 | 文件上传 |
操作一览
| 操作（锚点） | 能力域 | 说明 | 本平台绑定签名 | 功能页 |
|---|---|---|---|---|
init | 连接与监听 | 初始化 SDK（构造客户端实例）。幂等：同 appkey 重复初始化返回同一实例。 | static getInstance(options: IMClientOptions): IMClient | 初始化 |
connect | 连接与监听 | 使用用户 token 建立长连接：握手→hello→离线补发→sync_done；成功后触发 CONNECTED。失败按协议重连策略重试。 | connect(token: string): Promise<RcResult<ConnectResult>> | 建立连接 |
disconnect | 连接与监听 | 主动断开；停止重连、清理心跳与待决请求。 | disconnect(): Promise<RcResult<void>> | 建立连接 |
getConnectionStatus | 连接与监听 | 返回 ConnectionStatus 枚举值。 | getConnectionStatus(): ConnectionStatus | 建立连接 |
getCurrentUserId | 连接与监听 | 当前登录 userId；未登录返回空串。 | getCurrentUserId(): string | 连接监听 |
addEventListener | 连接与监听 | 注册事件监听；同一 handler 重复注册只生效一次。 | addEventListener(event: IMClientEvent, listener: IMClientEventListener): void | 连接监听 |
removeEventListener | 连接与监听 | 移除事件监听。 | removeEventListener(event: IMClientEvent, listener: IMClientEventListener): void | 连接监听 |
sendMessage | 消息 | 发送任意类型消息。优先走长连接；连接不可用（SUSPEND/DISCONNECTED）时按 SDK_NO_CONNECTION 失败并保留本地待发队列（可选实现）。rev23：options.channelId 用于超级群频道消息（conversationType=10），仅频道成员接收；消息模型带 channelId。 | sendMessage(conversationType: ConversationType, targetId: string, content: MessageContent, options?: SendOptions): Promise<RcResult<Message>> | 发送消息 |
sendTextMessage | 消息 | 发送文本消息；内部等价 sendMessage(content={type:'text',text,mentionedInfo?,quote?})。 | sendTextMessage(conversationType: ConversationType, targetId: string, text: string, options?: TextSendOptions): Promise<RcResult<Message>> | 发送消息 |
sendImageMessage | 消息 | 发送图片消息；url 由 uploadFile 或业务方上传得到。 | sendImageMessage(conversationType: ConversationType, targetId: string, content: ImageContent, options?: SendOptions): Promise<RcResult<Message>> | 发送消息 |
sendFileMessage | 消息 | 发送文件消息。 | sendFileMessage(conversationType: ConversationType, targetId: string, content: FileContent, options?: SendOptions): Promise<RcResult<Message>> | 发送消息 |
sendVoiceMessage | 消息 | 发送语音消息；duration 秒 1..300。 | sendVoiceMessage(conversationType: ConversationType, targetId: string, content: VoiceContent, options?: SendOptions): Promise<RcResult<Message>> | 发送消息 |
sendLocationMessage | 消息 | 发送位置消息；lat/lng 范围校验。 | sendLocationMessage(conversationType: ConversationType, targetId: string, content: LocationContent, options?: SendOptions): Promise<RcResult<Message>> | 发送消息 |
sendTypingStatus | 消息 | 发送正在输入状态；不持久化；对端触发 TYPING 事件。 | sendTypingStatus(conversationType: ConversationType, targetId: string, typing: boolean): Promise<RcResult<void>> | 输入状态 |
recallMessage | 消息 | 撤回消息（仅发送者、撤回时限内）。成功后本地与对端收到 MESSAGE_RECALLED。 | recallMessage(messageId: string): Promise<RcResult<Message>> | 消息管理 |
sendReadReceipt | 消息 | 上报已读回执；服务端记录唯一读者并推送给消息发送者。 | sendReadReceipt(conversationType: ConversationType, targetId: string, messageIds: string[]): Promise<RcResult<SendReadReceiptResult>> | 已读回执 |
getMessageReadCount | 消息 | 查询消息已读人数。 | getMessageReadCount(messageId: string): Promise<RcResult<MessageReadCount>> | 已读回执 |
getMessageReadUsers | 消息 | 查询已读用户明细（分页）。 | getMessageReadUsers(messageId: string, options?: PageOptions): Promise<RcResult<MessageReadUsers>> | 已读回执 |
getMessageReadDetail | 消息 | 查询单条消息的已读详情：已读/未读名单 + 具体读取时间（分页；filter=all|read|unread，默认 all）。 | getMessageReadDetail(messageId: string, options?: PageOptions): Promise<RcResult<MessageReadDetail>> | — |
searchMessages | 消息 | 在当前用户全部会话中搜索文本消息（倒序）。 | searchMessages(options: SearchMessagesOptions): Promise<RcResult<MessageSearchResult>> | 消息管理 |
getConversationList | 会话 | 会话列表：置顶优先、按 updatedAt 倒序；含未读/提及/草稿/免打扰。 | getConversationList(): Promise<RcResult<Conversation[]>> | 会话列表 |
getConversation | 会话 | 单会话详情。 | getConversation(conversationType: ConversationType, targetId: string): Promise<RcResult<Conversation>> | 会话列表 |
getHistoryMessages | 会话 | 历史消息分页（beforeSeq 向前翻页）；limit 默认 20 上限 100。rev23：channelId 过滤超级群频道消息（仅返回该频道消息）。 | getHistoryMessages(conversationType: ConversationType, targetId: string, options?: HistoryOptions): Promise<RcResult<HistoryPage>> | 历史消息 |
clearUnreadCount | 会话 | 清空会话未读（等价 read 帧 + 本地清零）。 | clearUnreadCount(conversationType: ConversationType, targetId: string): Promise<RcResult<void>> | 未读数 |
setConversationToTop | 会话 | 会话置顶/取消。 | setConversationToTop(conversationType: ConversationType, targetId: string, isTop: boolean): Promise<RcResult<void>> | 置顶与免打扰 |
saveTextMessageDraft | 会话 | 保存草稿（空串=清除）。 | saveTextMessageDraft(conversationType: ConversationType, targetId: string, draft: string): Promise<RcResult<void>> | 草稿 |
getTextMessageDraft | 会话 | 读取草稿；无草稿返回空串。 | getTextMessageDraft(conversationType: ConversationType, targetId: string): Promise<RcResult<string>> | 草稿 |
clearTextMessageDraft | 会话 | 清除草稿。 | clearTextMessageDraft(conversationType: ConversationType, targetId: string): Promise<RcResult<void>> | 草稿 |
setConversationNotificationLevel | 会话 | 会话提醒级别：0 全部 / 1 仅提及 / 2 免打扰。 | setConversationNotificationLevel(conversationType: ConversationType, targetId: string, level: NotificationLevel): Promise<RcResult<void>> | 置顶与免打扰 |
getUserProfile | 用户 | 查询用户资料。 | getUserProfile(userId: string): Promise<RcResult<UserProfile>> | 用户资料 |
updateMyUserProfile | 用户 | 修改本人资料（name/avatarUrl）。 | updateMyUserProfile(profile: UserProfileUpdate): Promise<RcResult<UserProfile>> | 用户资料 |
getOnlineStatus | 用户 | 查询单个用户在线状态。 | getOnlineStatus(userId: string): Promise<RcResult<UserOnlineStatus>> | 在线状态 |
getOnlineStatusBatch | 用户 | 批量在线状态（<=100）。 | getOnlineStatusBatch(userIds: string[]): Promise<RcResult<UserOnlineStatusBatch>> | 在线状态 |
searchUsers | 好友与黑名单 | 搜索用户（userId/name，大小写不敏感，排除自己）。 | searchUsers(keyword: string, options?: PageOptions): Promise<RcResult<UserSearchResult>> | 好友列表 |
sendFriendRequest | 好友与黑名单 | 发起好友申请；已是好友/已有 pending → 1003；被拉黑 → 1011。 | sendFriendRequest(toUserId: string, message?: string): Promise<RcResult<FriendRequest>> | 好友请求 |
getFriendRequests | 好友与黑名单 | 好友申请列表（incoming/outgoing，pending/all）。 | getFriendRequests(options?: FriendRequestQuery): Promise<RcResult<FriendRequest[]>> | 好友请求 |
acceptFriendRequest | 好友与黑名单 | 同意申请，双向建立好友关系。 | acceptFriendRequest(requestId: string): Promise<RcResult<FriendRequest>> | 好友请求 |
rejectFriendRequest | 好友与黑名单 | 拒绝申请。 | rejectFriendRequest(requestId: string): Promise<RcResult<FriendRequest>> | 好友请求 |
getFriends | 好友与黑名单 | 好友列表（含备注/在线/拉黑标记）。 | getFriends(): Promise<RcResult<Friend[]>> | 好友列表 |
deleteFriend | 好友与黑名单 | 双向删除好友。 | deleteFriend(friendId: string): Promise<RcResult<void>> | 好友列表 |
setFriendRemark | 好友与黑名单 | 设置好友备注（<=64 字，空串清除）。 | setFriendRemark(friendId: string, remark: string): Promise<RcResult<void>> | 好友列表 |
getBlacklist | 好友与黑名单 | 黑名单列表。 | getBlacklist(): Promise<RcResult<BlacklistEntry[]>> | 黑名单 |
addToBlacklist | 好友与黑名单 | 加入黑名单（幂等；不能拉黑自己→1001）。 | addToBlacklist(userId: string): Promise<RcResult<void>> | 黑名单 |
removeFromBlacklist | 好友与黑名单 | 移出黑名单。 | removeFromBlacklist(userId: string): Promise<RcResult<void>> | 黑名单 |
createGroup | 群组 | 创建群（groupType 缺省 normal；joinPolicy 缺省 open；maxMembers 对 super 有效）。groupId 可由调用方指定（唯一）或服务端生成。 | createGroup(options: CreateGroupOptions): Promise<IAsyncResult<Group>> | 创建群组 |
getGroupsInfo | 群组 | 批量查询群信息（<=20）。 | getGroupsInfo(groupIds: string[]): Promise<RcResult<Group[]>> | 创建群组 |
getGroupMembers | 群组 | 群成员列表（含角色/禁言）。 | getGroupMembers(groupId: string): Promise<RcResult<GroupMember[]>> | 群成员 |
addGroupMembers | 群组 | 拉人入群（群主/管理员；普通成员按配置）。 | addGroupMembers(groupId: string, userIds: string[]): Promise<RcResult<AddGroupMembersResult>> | 群成员 |
removeGroupMembers | 群组 | 移除成员（群主/管理员；权限检查）。 | removeGroupMembers(groupId: string, userIds: string[]): Promise<RcResult<RemoveGroupMembersResult>> | 群成员 |
quitGroup | 群组 | 退出群；群主需先转让。 | quitGroup(groupId: string): Promise<RcResult<void>> | 群成员 |
updateGroupName | 群组 | 修改群名（群主/管理员）。 | updateGroupName(groupId: string, name: string): Promise<RcResult<Group>> | 群管理 |
updateGroupNotice | 群组 | 设置群公告（群主/管理员，<=500 字，空串清除）。 | updateGroupNotice(groupId: string, notice: string): Promise<RcResult<Group>> | 群管理 |
transferGroupOwner | 群组 | 转让群主（新群主须为成员）。 | transferGroupOwner(groupId: string, newOwner: string): Promise<RcResult<Group>> | 群管理 |
addGroupAdmin | 群组 | 设置管理员（群主，幂等）。 | addGroupAdmin(groupId: string, userId: string): Promise<RcResult<Group>> | 群管理 |
removeGroupAdmin | 群组 | 取消管理员（群主）。 | removeGroupAdmin(groupId: string, userId: string): Promise<RcResult<Group>> | 群管理 |
muteGroupMember | 群组 | 禁言/解禁（群主/管理员；不能禁言群主；管理员不能禁言管理员）。 | muteGroupMember(groupId: string, userId: string, mutedUntil: number): Promise<RcResult<MuteGroupMemberResult>> | 群管理 |
createChatroom | 聊天室 | 创建聊天室（客户端能力；服务端 Open API 亦可创建）。chatroomId 可指定或服务端生成。 | createChatroom(options: CreateChatroomOptions): Promise<RcResult<Chatroom>> | 加入与退出 |
joinChatroom | 聊天室 | 加入聊天室：发送 chatroom_join，收到 chatroom_joined；房内广播 member_changed。 | joinChatroom(chatroomId: string): Promise<RcResult<Chatroom>> | 加入与退出 |
leaveChatroom | 聊天室 | 离开聊天室。 | leaveChatroom(chatroomId: string): Promise<RcResult<void>> | 加入与退出 |
getChatroomInfo | 聊天室 | 聊天室信息（含在线数）。 | getChatroomInfo(chatroomId: string): Promise<RcResult<Chatroom>> | 聊天室信息 |
getChatroomMembers | 聊天室 | 聊天室在线成员列表。 | getChatroomMembers(chatroomId: string, options?: PageOptions): Promise<RcResult<ChatroomMembersPage>> | 聊天室信息 |
getSystemMessages | 系统通知 | 系统通知历史（会话 conversationType=SYSTEM，targetId='system'）。 | getSystemMessages(options?: HistoryOptions): Promise<RcResult<HistoryPage>> | 系统通知 |
uploadFile | 文件上传 | 上传文件（<=20MB），返回可用于图片/文件/语音消息的 url。 | uploadFile(data: ArrayBuffer, name: string, mime?: string): Promise<RcResult<UploadResult>> | 文件上传 |
updateMessageExpansion | 消息 | 更新已发送消息的扩展 KV（合并语义）。仅单聊/群聊/超级群支持，且消息须在发送时开启可扩展；单次 ≤20 对、单条 ≤300 对，key 1-32 字符 [A-Za-z0-9+=_-]、value ≤4096。 | updateMessageExpansion(messageId: string, expansion: Record<string, string>): Promise<IAsyncResult<MessageExpansion>> | 消息进阶 |
removeMessageExpansion | 消息 | 删除消息扩展 KV（按 key）。语义与融云 removeMessageExpansion 对齐：消息须可扩展，删除不存在的 key 不报错。 | removeMessageExpansion(messageId: string, keys: Array<string>): Promise<IAsyncResult<MessageExpansion>> | 消息进阶 |
addMessageReaction | 消息 | 为指定消息添加回应（reactionId 由业务定义，1-16 字符；同一用户对同一消息同一 reactionId 重复添加视为幂等）。单条消息最多 50 种回应、每种回应最多 100 个用户。 | addMessageReaction(params: UpdateMessageReactionParam): Promise<IAsyncResult<MessageReaction>> | 消息进阶 |
removeMessageReaction | 消息 | 移除自己对指定消息的回应；reactionId 须与添加时一致，未添加过时返回成功（removed=false）。 | removeMessageReaction(params: UpdateMessageReactionParam): Promise<IAsyncResult<ReactionRemoval>> | 消息进阶 |
batchGetMessageReactionSummaries | 消息 | 批量查询消息回应摘要（1-100 个 messageId）。返回按 messageId 分组：每个回应含总数、当前用户是否已回应、最近参与用户（最多 10 个）；不存在回应的消息返回空数组。 | batchGetMessageReactionSummaries(params: MessageReactionSummaryQuery): Promise<IAsyncResult<Record<string, MessageReactionSummary[]>>> | 消息进阶 |
getMessageReactions | 消息 | 分页查询指定消息的回应列表（count 1-50，默认 20；pageToken 不透明，空串表示第一页）。 | getMessageReactions(params: GetMessageReactionsParam): Promise<IAsyncResult<MessageReactionPage>> | 消息进阶 |
getMessageReactionUsers | 消息 | 分页查询某个回应的参与用户（count 1-50，默认 20；pageToken 不透明）。 | getMessageReactionUsers(params: GetMessageReactionUsersParam): Promise<IAsyncResult<MessageReactionUserPage>> | 消息进阶 |
createConversationTag | 会话 | 创建会话标签（tagName ≤16；单用户 ≤20 个，超出抛 1031）。 | createConversationTag(params: CreateConversationTagParam): Promise<IAsyncResult<ConversationTag>> | 会话标签与分组 |
updateConversationTag | 会话 | 重命名会话标签。 | updateConversationTag(tagId: string, tagName: string): Promise<IAsyncResult<ConversationTag>> | 会话标签与分组 |
deleteConversationTag | 会话 | 删除会话标签（同时清除标签内会话引用）。 | deleteConversationTag(tagId: string): Promise<IAsyncResult<null>> | 会话标签与分组 |
getConversationTags | 会话 | 获取全部会话标签（含会话数量）。 | getConversationTags(): Promise<IAsyncResult<ConversationTag[]>> | 会话标签与分组 |
addConversationsToTag | 会话 | 把会话加入标签（≤100/次，幂等；≤1000/标签，超出抛 1033）。 | addConversationsToTag(tagId: string, conversations: ConversationRef[]): Promise<IAsyncResult<ConversationTagMembershipResult>> | 会话标签与分组 |
removeConversationsFromTag | 会话 | 把会话移出标签（≤100/次，幂等）。 | removeConversationsFromTag(tagId: string, conversations: ConversationRef[]): Promise<IAsyncResult<ConversationTagMembershipResult>> | 会话标签与分组 |
getConversationsFromTagByPage | 会话 | 分页获取标签内会话（含置顶/未读数/最后消息时间）。 | getConversationsFromTagByPage(tagId: string, options?: ConversationTagPageOptions): Promise<IAsyncResult<ConversationTagPage>> | 会话标签与分组 |
getTagsFromConversation | 会话 | 查询某个会话所属的标签列表。 | getTagsFromConversation(conversationType: number, targetId: string): Promise<IAsyncResult<ConversationTag[]>> | 会话标签与分组 |
getUnreadCountByTag | 会话 | 标签内未读汇总（消息总数 + 有未读的会话数）。 | getUnreadCountByTag(tagId: string): Promise<IAsyncResult<ConversationTagUnread>> | 会话标签与分组 |
setConversationToTopInTag | 会话 | 标签内置顶/取消置顶会话（同步会话会话级置顶状态）。 | setConversationToTopInTag(tagId: string, conversationType: number, targetId: string, top: boolean): Promise<IAsyncResult<null>> | 会话标签与分组 |
deleteConversation | 会话 | 删除会话记录（列表项/未读/草稿/置顶），历史消息保留；同时从标签移除；幂等。 | deleteConversation(conversationType: number, targetId: string): Promise<IAsyncResult<{ removed: boolean }>> | 会话删除与类型免打扰 |
getConversationTypeNotification | 会话 | 查询按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰）。 | getConversationTypeNotification(conversationType: number): Promise<IAsyncResult<ConversationTypeNotification>> | 会话删除与类型免打扰 |
setConversationTypeNotification | 会话 | 设置按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰）。 | setConversationTypeNotification(conversationType: number, level: number): Promise<IAsyncResult<ConversationTypeNotification>> | 会话删除与类型免打扰 |
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）。 | startStreamMessage(params: StartStreamMessageParams): Promise<IAsyncResult<StreamMessage>> | 消息进阶 |
appendStreamMessage | 消息 | 追加一个流式增量（IDL rev17；客户端 REST `POST /api/apps/{appkey}/messages/stream/append`），返回累计文本/分段/状态的 StreamMessage；服务端同时向会话全部在线参与者广播 `stream_changed`（complete=false）。`seq` 重复时覆盖该段（乱序安全）。仅流发送者可调用（其他人 1003）；流不存在 1001、已结束 1001。 | appendStreamMessage(streamId: string, delta: string, options?: AppendStreamMessageOptions): Promise<IAsyncResult<StreamMessage>> | 消息进阶 |
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。 | completeStreamMessage(streamId: string): Promise<IAsyncResult<StreamCompleteResult>> | 消息进阶 |
getStreamMessage | 消息 | 查询流式消息快照（IDL rev17；客户端 REST `GET /api/apps/{appkey}/messages/stream/{streamId}`），与 append 响应同形（StreamMessage）。仅会话参与者可见（单聊双方、群成员、聊天室在线成员；其他人 1003）；未知流 1001。 | getStreamMessage(streamId: string): Promise<IAsyncResult<StreamMessage>> | 消息进阶 |
getMessageExpansion | 消息 | 读取已发送消息的扩展 KV（IDL rev19；客户端 REST `GET /api/apps/{appkey}/messages/{messageId}/expansion`），返回 `{messageId, expansion}`；无扩展/已全部删除时 expansion 为空 map。仅会话参与者可读（非参与者 1003）；未知消息 1001；单聊对端用户不存在 1004、群不存在 1005、聊天室消息 1012。只读、幂等、不触发事件（写入仍由 updateMessageExpansion / removeMessageExpansion 完成）。 | getMessageExpansion(messageId: string): Promise<IAsyncResult<MessageExpansion>> | 消息进阶 |
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。 | combineMessages(messages: Message[], options?: CombineMessagesOptions): Promise<IAsyncResult<CombineContent>> | 消息进阶 |
subscribePresence | 用户 | 订阅用户在线状态（IDL rev20；客户端 REST `POST /api/apps/{appkey}/users/{userId}/presence/subscriptions`，userId 取自当前登录用户）。被订阅用户上线/离线/被踢/注销时通过长连接收到 `presence_changed`。订阅自己 1001；目标用户不存在/属于其它 app 1004；订阅总数上限 500（超限 1001）；幂等（重复订阅不重复入列）。成功返回变更后的完整订阅列表 `{subscribed:[...]}`。好友关系本身已默认订阅对方在线状态，无需额外调用。 | subscribePresence(userIds: string[]): Promise<IAsyncResult<PresenceSubscription>> | 在线状态订阅与推送令牌 |
unsubscribePresence | 用户 | 取消订阅用户在线状态（IDL rev20；客户端 REST `POST .../presence/subscriptions` 的 `unsubscribe` 分支）。取消未订阅的用户幂等成功（不报错）；订阅自己 1001；目标用户不存在 1004。成功返回变更后的完整订阅列表 `{subscribed:[...]}`。仅停止接收该用户的实时在线状态帧，好友关系不受影响。 | unsubscribePresence(userIds: string[]): Promise<IAsyncResult<PresenceSubscription>> | 在线状态订阅与推送令牌 |
getPresenceSubscriptions | 用户 | 查询当前用户的在线状态订阅列表（IDL rev20；客户端 REST `GET /api/apps/{appkey}/users/{userId}/presence/subscriptions`）→ `{userId,subscribed:[...]}`。只读、幂等、不产生事件。 | getPresenceSubscriptions(): Promise<IAsyncResult<PresenceSubscription>> | 在线状态订阅与推送令牌 |
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（设备换绑）。 | registerPushToken(options: RegisterPushTokenOptions): Promise<IAsyncResult<PushToken>> | 在线状态订阅与推送令牌 |
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）。 | unregisterPushToken(tokenId: string): Promise<IAsyncResult<UnregisterPushTokenResult>> | 在线状态订阅与推送令牌 |
getPushTokens | 用户 | 查询本人设备推送 token（IDL rev21 C23；客户端 REST `GET /api/apps/{appkey}/push/tokens`）→ `{userId,tokens:[PushToken],total,activeTotal,platforms}`；含 active=false 历史，按 createdAt 倒序。只读、幂等、不产生事件。 | getPushTokens(): Promise<IAsyncResult<PushTokenListResult>> | 在线状态订阅与推送令牌 |
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` 共享状态。 | createSupergroupChannel(params: CreateSupergroupChannelParams): Promise<IAsyncResult<SupergroupChannel>> | 超级群频道与用户组 |
listSupergroupChannels | 群组 | 超级群频道列表（IDL rev21 C17；客户端 REST `GET /api/apps/{appkey}/supergroup/channels?groupId=`）→ `{groupId,channels:[SupergroupChannel],total}`。仅群成员可读（否则 1003），群不存在 1005，缺 groupId 1001。 | listSupergroupChannels(groupId: string): Promise<IAsyncResult<SupergroupChannelListResult>> | 超级群频道与用户组 |
joinSupergroupChannel | 群组 | 加入超级群频道（IDL rev21 C17；客户端 REST `POST .../supergroup/channels/{channelId}/join`，幂等）→ `{groupId,channelId,userId,joined:true,alreadyJoined}`。public 频道群成员可直接加入；private 频道需已受邀或为群主/管理员（否则 1003）。频道不存在 1005；channelId 跨群同名时可通过第二参数 `{groupId}` 消歧（未消歧 1001）；非群成员 1003。 | joinSupergroupChannel(channelId: string, options?: SupergroupChannelOptions): Promise<IAsyncResult<JoinSupergroupChannelResult>> | 超级群频道与用户组 |
leaveSupergroupChannel | 群组 | 离开超级群频道（IDL rev21 C17；客户端 REST `POST .../supergroup/channels/{channelId}/leave`，幂等）→ `{groupId,channelId,userId,left:true,wasMember}`；不在频道内也返回成功（wasMember=false）。频道不存在 1005、非群成员 1003。 | leaveSupergroupChannel(channelId: string, options?: SupergroupChannelOptions): Promise<IAsyncResult<LeaveSupergroupChannelResult>> | 超级群频道与用户组 |
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。 | bindUserGroupToChannel(channelId: string, userGroupId: string, options?: SupergroupChannelOptions): Promise<IAsyncResult<BindUserGroupToChannelResult>> | 超级群频道与用户组 |
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.*` 共享状态。 | createUserGroup(params: CreateUserGroupParams): Promise<IAsyncResult<UserGroup>> | 超级群频道与用户组 |
listUserGroups | 群组 | 超级群用户组列表（IDL rev21 C17；客户端 REST `GET /api/apps/{appkey}/supergroup/usergroups?groupId=`）→ `{groupId,userGroups:[UserGroup],total}`；UserGroup.channelIds 为频道反向索引（rev21 修复后可用）。仅群成员可读（否则 1003），群不存在 1005，缺 groupId 1001。 | listUserGroups(groupId: string): Promise<IAsyncResult<UserGroupListResult>> | 超级群频道与用户组 |
getUserGroupsByUser | 群组 | 查询某用户所在的所有用户组（IDL rev21 C17；客户端 REST `GET .../supergroup/usergroups/by-user/{userId}`）→ `{userId,userGroups:[UserGroup],total}`。仅本人可查（userId ≠ 当前登录用户 1003）；`options.groupId` 可限定单个群；只返回「本人确实在该群」的用户组（群已删除的不返回，不虚构）。 | getUserGroupsByUser(userId: string, options?: SupergroupChannelOptions): Promise<IAsyncResult<UserGroupListResult>> | 超级群频道与用户组 |
操作详情索引
连接与监听（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）
getConversationList· 会话列表：置顶优先、按 updatedAt 倒序；含未读/提及/草稿/免打扰。getConversation· 单会话详情。getHistoryMessages· 历史消息分页（beforeSeq 向前翻页）；limit 默认 20 上限 100。rev23：channelId 过滤超级群频道消息（仅返回该频道消息）。clearUnreadCount· 清空会话未读（等价 read 帧 + 本地清零）。setConversationToTop· 会话置顶/取消。saveTextMessageDraft· 保存草稿（空串=清除）。getTextMessageDraft· 读取草稿；无草稿返回空串。clearTextMessageDraft· 清除草稿。setConversationNotificationLevel· 会话提醒级别：0 全部 / 1 仅提及 / 2 免打扰。createConversationTag· 创建会话标签（tagName ≤16；单用户 ≤20 个，超出抛 1031）。updateConversationTag· 重命名会话标签。deleteConversationTag· 删除会话标签（同时清除标签内会话引用）。getConversationTags· 获取全部会话标签（含会话数量）。addConversationsToTag· 把会话加入标签（≤100/次，幂等；≤1000/标签，超出抛 1033）。removeConversationsFromTag· 把会话移出标签（≤100/次，幂等）。getConversationsFromTagByPage· 分页获取标签内会话（含置顶/未读数/最后消息时间）。getTagsFromConversation· 查询某个会话所属的标签列表。getUnreadCountByTag· 标签内未读汇总（消息总数 + 有未读的会话数）。setConversationToTopInTag· 标签内置顶/取消置顶会话（同步会话会话级置顶状态）。deleteConversation· 删除会话记录（列表项/未读/草稿/置顶），历史消息保留；同时从标签移除；幂等。getConversationTypeNotification· 查询按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰）。setConversationTypeNotification· 设置按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰）。
用户（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）
searchUsers· 搜索用户（userId/name，大小写不敏感，排除自己）。sendFriendRequest· 发起好友申请；已是好友/已有 pending → 1003；被拉黑 → 1011。getFriendRequests· 好友申请列表（incoming/outgoing，pending/all）。acceptFriendRequest· 同意申请，双向建立好友关系。rejectFriendRequest· 拒绝申请。getFriends· 好友列表（含备注/在线/拉黑标记）。deleteFriend· 双向删除好友。setFriendRemark· 设置好友备注（<=64 字，空串清除）。getBlacklist· 黑名单列表。addToBlacklist· 加入黑名单（幂等；不能拉黑自己→1001）。removeFromBlacklist· 移出黑名单。
群组（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。