Native (C ABI) IMLib 功能列表

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

分组统计​

操作一览​

操作详情索引​

连接与监听（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。