macOS IMLib 功能列表

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

分组统计​

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

操作一览​

操作（锚点）能力域说明本平台绑定签名功能页
init连接与监听初始化 SDK（构造客户端实例）。幂等：同 appkey 重复初始化返回同一实例。init(options: IMClientOptions): IMClient初始化
connect连接与监听使用用户 token 建立长连接：握手→hello→离线补发→sync_done；成功后触发 CONNECTED。失败按协议重连策略重试。connect(token: string, opts?: {kickOtherDevice?: boolean}): Promise<RcResult<{userId: string; sessionId?: string}>>建立连接
disconnect连接与监听主动断开；停止重连、清理心跳与待决请求。disconnect(opts?: {closeDb?: boolean; disablePush?: boolean}): Promise<RcResult<null>>建立连接
getConnectionStatus连接与监听返回 ConnectionStatus 枚举值。getConnectionStatus(): ConnectionStatus建立连接
getCurrentUserId连接与监听当前登录 userId；未登录返回空串。getCurrentUserId(): string连接监听
addEventListener连接与监听注册事件监听；同一 handler 重复注册只生效一次。addEventListener(event: Events, handler: (payload: unknown) => void): () => void连接监听
removeEventListener连接与监听移除事件监听。removeEventListener(event: Events, handler: Function): 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?: SendOptions): Promise<RcResult<Message>>发送消息
sendImageMessage消息发送图片消息；url 由 uploadFile 或业务方上传得到。sendImageMessage(conversationType: ConversationType, targetId: string, content: {url: string; width?: number; height?: number; size?: number; localPath?: string}, options?: SendOptions): Promise<RcResult<Message>>发送消息
sendFileMessage消息发送文件消息。sendFileMessage(conversationType: ConversationType, targetId: string, content: {url: string; name: string; size?: number; mime?: string; localPath?: string}, options?: SendOptions): Promise<RcResult<Message>>发送消息
sendVoiceMessage消息发送语音消息；duration 秒 1..300。sendVoiceMessage(conversationType: ConversationType, targetId: string, content: {url: string; duration: number; localPath?: string}, options?: SendOptions): Promise<RcResult<Message>>发送消息
sendLocationMessage消息发送位置消息；lat/lng 范围校验。sendLocationMessage(conversationType: ConversationType, targetId: string, content: {latitude: number; longitude: number; address?: string}, options?: SendOptions): Promise<RcResult<Message>>发送消息
sendTypingStatus消息发送正在输入状态；不持久化；对端触发 TYPING 事件。sendTypingStatus(conversationType: ConversationType, targetId: string, typing: boolean): Promise<RcResult<null>>输入状态
recallMessage消息撤回消息（仅发送者、撤回时限内）。成功后本地与对端收到 MESSAGE_RECALLED。recallMessage(messageId: string | number): Promise<RcResult<Message>>消息管理
sendReadReceipt消息上报已读回执；服务端记录唯一读者并推送给消息发送者。sendReadReceipt(conversationType: ConversationType, targetId: string, messageIds: string[]): Promise<RcResult<{messageIds: string[]; readCounts?: Record<string, number>; totalMembers?: number}>>已读回执
getMessageReadCount消息查询消息已读人数。getMessageReadCount(messageId: string | number): Promise<RcResult<{messageId: string; readCount: number; totalMembers: number}>>已读回执
getMessageReadUsers消息查询已读用户明细（分页）。getMessageReadUsers(messageId: string | number, options?: {offset?: number; limit?: number}): Promise<RcResult<{messageId: string; readCount: number; totalMembers: number; readers: UserProfile[]}>>已读回执
getMessageReadDetail消息查询单条消息的已读详情：已读/未读名单 + 具体读取时间（分页；filter=all|read|unread，默认 all）。getMessageReadDetail(messageId: string | number, options?: {offset?: number; limit?: number; filter?: string}): Promise<RcResult<{messageId: string; readCount: number; unreadCount: number; totalMembers: number; items: MessageReadDetailItem[]; hasMore: boolean}>>—
searchMessages消息在当前用户全部会话中搜索文本消息（倒序）。searchMessages(options: {keyword: string; limit?: number; conversationType?: ConversationType; targetId?: string; range?: {start?: number; end?: number}}): Promise<RcResult<{messages: Message[]; total: number}>>消息管理
getConversationList会话会话列表：置顶优先、按 updatedAt 倒序；含未读/提及/草稿/免打扰。getConversationList(options?: {limit?: number; beforeTime?: number; topPriority?: boolean}): 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?: {limit?: number; beforeSeq?: number; beforeTime?: number; order?: 0 | 1; source?: 'local' | 'remote' | 'auto'}): Promise<RcResult<{messages: Message[]; hasMore: boolean}>>历史消息
clearUnreadCount会话清空会话未读（等价 read 帧 + 本地清零）。clearUnreadCount(conversationType: ConversationType, targetId: string, options?: {untilTime?: number}): Promise<RcResult<null>>未读数
setConversationToTop会话会话置顶/取消。setConversationToTop(conversationType: ConversationType, targetId: string, isTop: boolean): Promise<RcResult<null>>置顶与免打扰
saveTextMessageDraft会话保存草稿（空串=清除）。saveTextMessageDraft(conversationType: ConversationType, targetId: string, draft: string): Promise<RcResult<null>>草稿
getTextMessageDraft会话读取草稿；无草稿返回空串。getTextMessageDraft(conversationType: ConversationType, targetId: string): Promise<RcResult<string>>草稿
clearTextMessageDraft会话清除草稿。clearTextMessageDraft(conversationType: ConversationType, targetId: string): Promise<RcResult<null>>草稿
setConversationNotificationLevel会话会话提醒级别：0 全部 / 1 仅提及 / 2 免打扰。setConversationNotificationLevel(conversationType: ConversationType, targetId: string, level: NotificationLevel): Promise<RcResult<null>>置顶与免打扰
getUserProfile用户查询用户资料。getUserProfile(userId: string): Promise<RcResult<UserProfile>>用户资料
updateMyUserProfile用户修改本人资料（name/avatarUrl）。updateMyUserProfile(profile: {name?: string; avatarUrl?: string}): Promise<RcResult<UserProfile>>用户资料
getOnlineStatus用户查询单个用户在线状态。getOnlineStatus(userId: string): Promise<RcResult<{userId: string; online: boolean; sessionCount: number}>>在线状态
getOnlineStatusBatch用户批量在线状态（<=100）。getOnlineStatusBatch(userIds: string[]): Promise<RcResult<{items: Array<{userId: string; online: boolean; sessionCount: number}>}>>在线状态
searchUsers好友与黑名单搜索用户（userId/name，大小写不敏感，排除自己）。searchUsers(keyword: string, options?: {limit?: number}): Promise<RcResult<{users: Array<{userId: string; name: string; isFriend: boolean; blacklisted: boolean}>; total: number}>>好友列表
sendFriendRequest好友与黑名单发起好友申请；已是好友/已有 pending → 1003；被拉黑 → 1011。sendFriendRequest(toUserId: string, message?: string): Promise<RcResult<FriendRequest>>好友请求
getFriendRequests好友与黑名单好友申请列表（incoming/outgoing，pending/all）。getFriendRequests(options?: {type?: 'incoming' | 'outgoing'; status?: 'pending' | 'all'}): Promise<RcResult<FriendRequest[]>>好友请求
acceptFriendRequest好友与黑名单同意申请，双向建立好友关系。acceptFriendRequest(requestId: string): Promise<RcResult<FriendRequest>>好友请求
rejectFriendRequest好友与黑名单拒绝申请。rejectFriendRequest(requestId: string): Promise<RcResult<FriendRequest>>好友请求
getFriends好友与黑名单好友列表（含备注/在线/拉黑标记）。getFriends(): Promise<RcResult<Array<{userId: string; name?: string; avatarUrl?: string; remark?: string; online?: boolean; blacklisted?: boolean}>>>好友列表
deleteFriend好友与黑名单双向删除好友。deleteFriend(friendId: string): Promise<RcResult<null>>好友列表
setFriendRemark好友与黑名单设置好友备注（<=64 字，空串清除）。setFriendRemark(friendId: string, remark: string): Promise<RcResult<null>>好友列表
getBlacklist好友与黑名单黑名单列表。getBlacklist(): Promise<RcResult<Array<{userId: string; name?: string}>>>黑名单
addToBlacklist好友与黑名单加入黑名单（幂等；不能拉黑自己→1001）。addToBlacklist(userId: string): Promise<RcResult<null>>黑名单
removeFromBlacklist好友与黑名单移出黑名单。removeFromBlacklist(userId: string): Promise<RcResult<null>>黑名单
createGroup群组创建群（groupType 缺省 normal；joinPolicy 缺省 open；maxMembers 对 super 有效）。groupId 可由调用方指定（唯一）或服务端生成。createGroup(options: {groupId?: string; name: string; owner?: string; members?: string[]; groupType?: GroupType}): Promise<RcResult<Group>>创建群组
getGroupsInfo群组批量查询群信息（<=20）。getGroupsInfo(groupIds: string[]): Promise<RcResult<Group[]>>创建群组
getGroupMembers群组群成员列表（含角色/禁言）。getGroupMembers(groupId: string): Promise<RcResult<GroupMember[]>>群成员
addGroupMembers群组拉人入群（群主/管理员；普通成员按配置）。addGroupMembers(groupId: string, userIds: string[]): Promise<RcResult<{added: string[]; group: Group}>>群成员
removeGroupMembers群组移除成员（群主/管理员；权限检查）。removeGroupMembers(groupId: string, userIds: string[]): Promise<RcResult<{removed: string[]}>>群成员
quitGroup群组退出群；群主需先转让。quitGroup(groupId: string): Promise<RcResult<null>>群成员
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<{groupId: string; userId: string; mutedUntil: number; group: Group}>>群管理
createChatroom聊天室创建聊天室（客户端能力；服务端 Open API 亦可创建）。chatroomId 可指定或服务端生成。createChatroom(options: {chatroomId?: string; name: string; owner?: string}): Promise<RcResult<Chatroom>>加入与退出
joinChatroom聊天室加入聊天室：发送 chatroom_join，收到 chatroom_joined；房内广播 member_changed。joinChatroom(chatroomId: string): Promise<RcResult<Chatroom>>加入与退出
leaveChatroom聊天室离开聊天室。leaveChatroom(chatroomId: string): Promise<RcResult<null>>加入与退出
getChatroomInfo聊天室聊天室信息（含在线数）。getChatroomInfo(chatroomId: string): Promise<RcResult<Chatroom>>聊天室信息
getChatroomMembers聊天室聊天室在线成员列表。getChatroomMembers(chatroomId: string, options?: {offset?: number; limit?: number}): Promise<RcResult<{members: ChatroomMember[]; total: number}>>聊天室信息
getSystemMessages系统通知系统通知历史（会话 conversationType=SYSTEM，targetId='system'）。getSystemMessages(options?: {limit?: number; beforeSeq?: number}): Promise<RcResult<{messages: Message[]; hasMore: boolean}>>系统通知
uploadFile文件上传上传文件（<=20MB），返回可用于图片/文件/语音消息的 url。uploadFile(data: Uint8Array | Blob | {path: string}, name: string, mime?: string, options?: {onProgress?: (percent: number) => void; signal?: AbortSignal}): Promise<RcResult<{url: string; name: string; size: number; mime: string; fullUrl?: string}>>文件上传
updateMessageExpansion消息更新已发送消息的扩展 KV（合并语义）。仅单聊/群聊/超级群支持，且消息须在发送时开启可扩展；单次 ≤20 对、单条 ≤300 对，key 1-32 字符 [A-Za-z0-9+=_-]、value ≤4096。updateMessageExpansion(messageId: string, expansion: Record<string, string>): Promise<RcResult<MessageExpansion>>消息进阶
removeMessageExpansion消息删除消息扩展 KV（按 key）。语义与融云 removeMessageExpansion 对齐：消息须可扩展，删除不存在的 key 不报错。removeMessageExpansion(messageId: string, keys: string[]): Promise<RcResult<MessageExpansion>>消息进阶
addMessageReaction消息为指定消息添加回应（reactionId 由业务定义，1-16 字符；同一用户对同一消息同一 reactionId 重复添加视为幂等）。单条消息最多 50 种回应、每种回应最多 100 个用户。addMessageReaction(params: UpdateMessageReactionParam): Promise<RcResult<MessageReaction>>消息进阶
removeMessageReaction消息移除自己对指定消息的回应；reactionId 须与添加时一致，未添加过时返回成功（removed=false）。removeMessageReaction(params: UpdateMessageReactionParam): Promise<RcResult<{ messageId: string; reactionId: string; removed: boolean }>>消息进阶
batchGetMessageReactionSummaries消息批量查询消息回应摘要（1-100 个 messageId）。返回按 messageId 分组：每个回应含总数、当前用户是否已回应、最近参与用户（最多 10 个）；不存在回应的消息返回空数组。batchGetMessageReactionSummaries(params: MessageReactionSummaryQuery): Promise<RcResult<Record<string, MessageReactionSummary[]>>>消息进阶
getMessageReactions消息分页查询指定消息的回应列表（count 1-50，默认 20；pageToken 不透明，空串表示第一页）。getMessageReactions(params: GetMessageReactionsParam): Promise<RcResult<MessageReactionPage>>消息进阶
getMessageReactionUsers消息分页查询某个回应的参与用户（count 1-50，默认 20；pageToken 不透明）。getMessageReactionUsers(params: GetMessageReactionUsersParam): Promise<RcResult<MessageReactionUserPage>>消息进阶
createConversationTag会话创建会话标签（tagName ≤16；单用户 ≤20 个，超出抛 1031）。createConversationTag(params: CreateConversationTagParam): Promise<RcResult<ConversationTag>>会话标签与分组
updateConversationTag会话重命名会话标签。updateConversationTag(tagId: string, tagName: string): Promise<RcResult<ConversationTag>>会话标签与分组
deleteConversationTag会话删除会话标签（同时清除标签内会话引用）。deleteConversationTag(tagId: string): Promise<RcResult<null>>会话标签与分组
getConversationTags会话获取全部会话标签（含会话数量）。getConversationTags(): Promise<RcResult<ConversationTag[]>>会话标签与分组
addConversationsToTag会话把会话加入标签（≤100/次，幂等；≤1000/标签，超出抛 1033）。addConversationsToTag(tagId: string, conversations: ConversationRef[]): Promise<RcResult<ConversationTagMembershipResult>>会话标签与分组
removeConversationsFromTag会话把会话移出标签（≤100/次，幂等）。removeConversationsFromTag(tagId: string, conversations: ConversationRef[]): Promise<RcResult<ConversationTagMembershipResult>>会话标签与分组
getConversationsFromTagByPage会话分页获取标签内会话（含置顶/未读数/最后消息时间）。getConversationsFromTagByPage(tagId: string, options?: ConversationTagPageOptions): Promise<RcResult<ConversationTagPage>>会话标签与分组
getTagsFromConversation会话查询某个会话所属的标签列表。getTagsFromConversation(conversationType: ConversationTypeValue, targetId: string): Promise<RcResult<ConversationTag[]>>会话标签与分组
getUnreadCountByTag会话标签内未读汇总（消息总数 + 有未读的会话数）。getUnreadCountByTag(tagId: string): Promise<RcResult<ConversationTagUnread>>会话标签与分组
setConversationToTopInTag会话标签内置顶/取消置顶会话（同步会话会话级置顶状态）。setConversationToTopInTag(tagId: string, conversationType: ConversationTypeValue, targetId: string, top: boolean): Promise<RcResult<null>>会话标签与分组
deleteConversation会话删除会话记录（列表项/未读/草稿/置顶），历史消息保留；同时从标签移除；幂等。deleteConversation(conversationType: ConversationTypeValue, targetId: string): Promise<RcResult<{ removed: boolean }>>会话删除与类型免打扰
getConversationTypeNotification会话查询按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰）。getConversationTypeNotification(conversationType: ConversationTypeValue): Promise<RcResult<{ conversationType: number; level: number }>>会话删除与类型免打扰
setConversationTypeNotification会话设置按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰）。setConversationTypeNotification(conversationType: ConversationTypeValue, level: 0 | 1 | 2): Promise<RcResult<{ conversationType: number; level: number }>>会话删除与类型免打扰
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<RcResult<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<RcResult<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<RcResult<{ messageId: string; text: string }>>消息进阶
getStreamMessage消息查询流式消息快照（IDL rev17；客户端 REST `GET /api/apps/{appkey}/messages/stream/{streamId}`），与 append 响应同形（StreamMessage）。仅会话参与者可见（单聊双方、群成员、聊天室在线成员；其他人 1003）；未知流 1001。getStreamMessage(streamId: string): Promise<RcResult<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 | number): Promise<RcResult<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<RcResult<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<RcResult<{subscribed: string[]}>>在线状态订阅与推送令牌
unsubscribePresence用户取消订阅用户在线状态（IDL rev20；客户端 REST `POST .../presence/subscriptions` 的 `unsubscribe` 分支）。取消未订阅的用户幂等成功（不报错）；订阅自己 1001；目标用户不存在 1004。成功返回变更后的完整订阅列表 `{subscribed:[...]}`。仅停止接收该用户的实时在线状态帧，好友关系不受影响。unsubscribePresence(userIds: string[]): Promise<RcResult<{subscribed: string[]}>>在线状态订阅与推送令牌
getPresenceSubscriptions用户查询当前用户的在线状态订阅列表（IDL rev20；客户端 REST `GET /api/apps/{appkey}/users/{userId}/presence/subscriptions`）→ `{userId,subscribed:[...]}`。只读、幂等、不产生事件。getPresenceSubscriptions(): Promise<RcResult<{userId: string, subscribed: string[]}>>在线状态订阅与推送令牌
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<RcResult<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<RcResult<UnregisterPushTokenResult>>在线状态订阅与推送令牌
getPushTokens用户查询本人设备推送 token（IDL rev21 C23；客户端 REST `GET /api/apps/{appkey}/push/tokens`）→ `{userId,tokens:[PushToken],total,activeTotal,platforms}`；含 active=false 历史，按 createdAt 倒序。只读、幂等、不产生事件。getPushTokens(): Promise<RcResult<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<RcResult<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<RcResult<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<RcResult<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<RcResult<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<RcResult<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<RcResult<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<RcResult<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<RcResult<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）​

用户（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。