RCIMIWEngine 类（Flutter IMLib）

类继承图

Object→RCIMIWEngine

继承关系：Object → RCIMIWEngine。初始化方法为 SDK 唯一入口；实例由初始化接口返回，不直接 new。

类说明

RCIMIWEngine 是 Flutter IMLib 的入口类：持有连接与事件总线，串联连接、消息、会话、用户、好友、群组、聊天室与文件上传共 62 个语义操作。方法名与 IDL 语义 op 同名，仅调用风格与常量名随平台变化。

项	值
程序包	impaas_imlib
完整声明	`impaas_imlib / impaas_imkit`
语言 / 运行时	Dart
初始化入口	`RCIMIWEngine.create(appKey, options)`
异步模型	Future<RcResult<T>>
事件 API	`engine.events.listen((event) => ...) / engine.addEventListener(name, handler)`
命名约定	camelCase，方法名与语义 op 同名
方法总数	103 个语义操作，本平台导出 103 个
平台状态	已交付

概要

方法按能力域分组。点击方法名跳转到详细说明；"签名"列逐字来自平台绑定的 methodMap。

连接与监听（7）

方法	签名（本平台绑定）	说明
`init`	`RCIMIWEngine.create(String appKey, RCIMIWEngineOptions options)`	初始化 SDK（构造客户端实例）
`connect`	`connect(String token, int timeout, {RCIMIWConnectCallback? callback})`	使用用户 token 建立长连接：握手→hello→离线补发→sync_done
`disconnect`	`disconnect(bool receivePush)`	主动断开
`getConnectionStatus`	`getConnectionStatus()`	返回 ConnectionStatus 枚举值
`getCurrentUserId`	`getCurrentUserId()`	当前登录 userId
`addEventListener`	`addEventListener(String event, void Function(Object?) handler)`	注册事件监听
`removeEventListener`	`removeEventListener(String event, void Function(Object?) handler)`	移除事件监听

功能指南：建立连接、连接监听

消息（26）

方法	签名（本平台绑定）	说明
`sendMessage`	`sendMessage(int conversationType, String targetId, MessageContent content, {MessageOptions? options})`	发送任意类型消息
`sendTextMessage`	`sendTextMessage(int conversationType, String targetId, String text, {MessageOptions? options})`	发送文本消息
`sendImageMessage`	`sendImageMessage(int conversationType, String targetId, ImageContent content, {MessageOptions? options})`	发送图片消息
`sendFileMessage`	`sendFileMessage(int conversationType, String targetId, FileContent content, {MessageOptions? options})`	发送文件消息
`sendVoiceMessage`	`sendVoiceMessage(int conversationType, String targetId, VoiceContent content, {MessageOptions? options})`	发送语音消息
`sendLocationMessage`	`sendLocationMessage(int conversationType, String targetId, LocationContent content, {MessageOptions? options})`	发送位置消息
`sendTypingStatus`	`sendTypingStatus(int conversationType, String targetId, bool typing)`	发送正在输入状态
`recallMessage`	`recallMessage(String messageId)`	撤回消息（仅发送者、撤回时限内）
`sendReadReceipt`	`sendReadReceipt(int conversationType, String targetId, List<String> messageIds)`	上报已读回执
`getMessageReadCount`	`getMessageReadCount(String messageId)`	查询消息已读人数
`getMessageReadUsers`	`getMessageReadUsers(String messageId, {int offset, int limit})`	查询已读用户明细（分页）
`getMessageReadDetail`	`getMessageReadDetail(String messageId, {int offset, int limit, String? filter})`	查询单条消息的已读详情：已读/未读名单 + 具体读取时间（分页）
`searchMessages`	`searchMessages({required String keyword, int limit})`	在当前用户全部会话中搜索文本消息（倒序）
`updateMessageExpansion`	`updateMessageExpansion(String messageId, Map<String, String> expansion)`	更新已发送消息的扩展 KV（合并语义）
`removeMessageExpansion`	`removeMessageExpansion(String messageId, List<String> keys)`	删除消息扩展 KV（按 key）
`addMessageReaction`	`addMessageReaction(int conversationType, String targetId, String messageId, String reactionId)`	为指定消息添加回应（reactionId 由业务定义，1-16 字符）
`removeMessageReaction`	`removeMessageReaction(int conversationType, String targetId, String messageId, String reactionId)`	移除自己对指定消息的回应
`batchGetMessageReactionSummaries`	`batchGetMessageReactionSummaries(int conversationType, String targetId, List<String> messageIds)`	批量查询消息回应摘要（1-100 个 messageId）
`getMessageReactions`	`getMessageReactions(int conversationType, String targetId, String messageId, {int? count, String? pageToken})`	分页查询指定消息的回应列表（count 1-50，默认 20）
`getMessageReactionUsers`	`getMessageReactionUsers(int conversationType, String targetId, String messageId, String reactionId, {int? coun…`	分页查询某个回应的参与用户（count 1-50，默认 20）
`startStreamMessage`	`startStreamMessage(int conversationType, String targetId, {StartStreamMessageOptions? options})`	开始一条流式消息（IDL rev17）
`appendStreamMessage`	`appendStreamMessage(String streamId, String delta, {AppendStreamMessageOptions? options})`	追加一个流式增量（IDL rev17）
`completeStreamMessage`	`completeStreamMessage(String streamId)`	结束流式消息（IDL rev17）
`getStreamMessage`	`getStreamMessage(String streamId)`	查询流式消息快照（IDL rev17）
`getMessageExpansion`	`getMessageExpansion(String messageId)`	读取已发送消息的扩展 KV（IDL rev19）
`combineMessages`	`combineMessages(List<Message> messages, {CombineMessagesOptions? options})`	本地构造合并转发内容（IDL rev19，transport=local，不做网络 IO）：把 Message[] 转换为 `{type:'co…

功能指南：发送消息、接收消息、消息管理、已读回执、输入状态、消息进阶

会话（22）

方法	签名（本平台绑定）	说明
`getConversationList`	`getConversationList()`	会话列表：置顶优先、按 updatedAt 倒序
`getConversation`	`getConversation(int conversationType, String targetId)`	单会话详情
`getHistoryMessages`	`getHistoryMessages(int conversationType, String targetId, {int limit, int? beforeSeq, String? channelId})`	历史消息分页（beforeSeq 向前翻页）
`clearUnreadCount`	`clearUnreadCount(int conversationType, String targetId)`	清空会话未读（等价 read 帧 + 本地清零）
`setConversationToTop`	`setConversationToTop(int conversationType, String targetId, bool isTop)`	会话置顶/取消
`saveTextMessageDraft`	`saveTextMessageDraft(int conversationType, String targetId, String draft)`	保存草稿（空串=清除）
`getTextMessageDraft`	`getTextMessageDraft(int conversationType, String targetId)`	读取草稿
`clearTextMessageDraft`	`clearTextMessageDraft(int conversationType, String targetId)`	清除草稿
`setConversationNotificationLevel`	`setConversationNotificationLevel(int conversationType, String targetId, int level)`	会话提醒级别：0 全部 / 1 仅提及 / 2 免打扰
`createConversationTag`	`createConversationTag(String tagName, {CreateConversationTagOptions? options})`	创建会话标签（tagName ≤16）
`updateConversationTag`	`updateConversationTag(String tagId, String tagName)`	重命名会话标签
`deleteConversationTag`	`deleteConversationTag(String tagId)`	删除会话标签（同时清除标签内会话引用）
`getConversationTags`	`getConversationTags()`	获取全部会话标签（含会话数量）
`addConversationsToTag`	`addConversationsToTag(String tagId, List<ConversationRef> conversations)`	把会话加入标签（≤100/次，幂等）
`removeConversationsFromTag`	`removeConversationsFromTag(String tagId, List<ConversationRef> conversations)`	把会话移出标签（≤100/次，幂等）
`getConversationsFromTagByPage`	`getConversationsFromTagByPage(String tagId, {ConversationTagPageOptions? options})`	分页获取标签内会话（含置顶/未读数/最后消息时间）
`getTagsFromConversation`	`getTagsFromConversation(int conversationType, String targetId)`	查询某个会话所属的标签列表
`getUnreadCountByTag`	`getUnreadCountByTag(String tagId)`	标签内未读汇总（消息总数 + 有未读的会话数）
`setConversationToTopInTag`	`setConversationToTopInTag(String tagId, int conversationType, String targetId, bool top)`	标签内置顶/取消置顶会话（同步会话会话级置顶状态）
`deleteConversation`	`deleteConversation(int conversationType, String targetId)`	删除会话记录（列表项/未读/草稿/置顶），历史消息保留
`getConversationTypeNotification`	`getConversationTypeNotification(int conversationType)`	查询按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰）
`setConversationTypeNotification`	`setConversationTypeNotification(int conversationType, int level)`	设置按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰）

功能指南：历史消息、会话列表、未读数、草稿、置顶与免打扰、会话标签与分组、会话删除与类型免打扰

用户（10）

方法	签名（本平台绑定）	说明
`getUserProfile`	`getUserProfile(String userId)`	查询用户资料
`updateMyUserProfile`	`updateMyUserProfile({String? name, String? avatarUrl})`	修改本人资料（name/avatarUrl）
`getOnlineStatus`	`getOnlineStatus(String userId)`	查询单个用户在线状态
`getOnlineStatusBatch`	`getOnlineStatusBatch(List<String> userIds)`	批量在线状态（<=100）
`subscribePresence`	`subscribePresence(List<String> userIds)`	订阅用户在线状态（IDL rev20）
`unsubscribePresence`	`unsubscribePresence(List<String> userIds)`	取消订阅用户在线状态（IDL rev20）
`getPresenceSubscriptions`	`getPresenceSubscriptions()`	查询当前用户的在线状态订阅列表（IDL rev20）
`registerPushToken`	`registerPushToken(RegisterPushTokenOptions options)`	注册设备推送 token（IDL rev21 C23 收口）
`unregisterPushToken`	`unregisterPushToken(String tokenId)`	注销本人设备推送 token（IDL rev21 C23）
`getPushTokens`	`getPushTokens()`	查询本人设备推送 token（IDL rev21 C23）

功能指南：用户资料、在线状态、在线状态订阅与推送令牌

好友与黑名单（11）

方法	签名（本平台绑定）	说明
`searchUsers`	`searchUsers(String keyword, {int limit})`	搜索用户（userId/name，大小写不敏感，排除自己）
`sendFriendRequest`	`sendFriendRequest(String toUserId, {String? message})`	发起好友申请
`getFriendRequests`	`getFriendRequests({String? type, String? status})`	好友申请列表（incoming/outgoing，pending/all）
`acceptFriendRequest`	`acceptFriendRequest(String requestId)`	同意申请，双向建立好友关系
`rejectFriendRequest`	`rejectFriendRequest(String requestId)`	拒绝申请
`getFriends`	`getFriends()`	好友列表（含备注/在线/拉黑标记）
`deleteFriend`	`deleteFriend(String friendId)`	双向删除好友
`setFriendRemark`	`setFriendRemark(String friendId, String remark)`	设置好友备注（<=64 字，空串清除）
`getBlacklist`	`getBlacklist()`	黑名单列表
`addToBlacklist`	`addToBlacklist(String userId)`	加入黑名单（幂等）
`removeFromBlacklist`	`removeFromBlacklist(String userId)`	移出黑名单

功能指南：好友列表、好友请求、黑名单

群组（20）

方法	签名（本平台绑定）	说明
`createGroup`	`createGroup(String name, List<String> memberIds, {String? groupId, String? owner, GroupOptions? options})`	创建群（groupType 缺省 normal）
`getGroupsInfo`	`getGroupsInfo(List<String> groupIds)`	批量查询群信息（<=20）
`getGroupMembers`	`getGroupMembers(String groupId)`	群成员列表（含角色/禁言）
`addGroupMembers`	`addGroupMembers(String groupId, List<String> userIds)`	拉人入群（群主/管理员）
`removeGroupMembers`	`removeGroupMembers(String groupId, List<String> userIds)`	移除成员（群主/管理员）
`quitGroup`	`quitGroup(String groupId)`	退出群
`updateGroupName`	`updateGroupName(String groupId, String name)`	修改群名（群主/管理员）
`updateGroupNotice`	`updateGroupNotice(String groupId, String notice)`	设置群公告（群主/管理员，<=500 字，空串清除）
`transferGroupOwner`	`transferGroupOwner(String groupId, String newOwner)`	转让群主（新群主须为成员）
`addGroupAdmin`	`addGroupAdmin(String groupId, String userId)`	设置管理员（群主，幂等）
`removeGroupAdmin`	`removeGroupAdmin(String groupId, String userId)`	取消管理员（群主）
`muteGroupMember`	`muteGroupMember(String groupId, String userId, int mutedUntil)`	禁言/解禁（群主/管理员）
`createSupergroupChannel`	`createSupergroupChannel(CreateSupergroupChannelParams params)`	创建超级群频道（IDL rev21 C17）
`listSupergroupChannels`	`listSupergroupChannels(String groupId)`	超级群频道列表（IDL rev21 C17）
`joinSupergroupChannel`	`joinSupergroupChannel(String channelId, {SupergroupChannelOptions? options})`	加入超级群频道（IDL rev21 C17）
`leaveSupergroupChannel`	`leaveSupergroupChannel(String channelId, {SupergroupChannelOptions? options})`	离开超级群频道（IDL rev21 C17）
`bindUserGroupToChannel`	`bindUserGroupToChannel(String channelId, String userGroupId, {SupergroupChannelOptions? options})`	把用户组绑定到频道（IDL rev21 C17）
`createUserGroup`	`createUserGroup(CreateUserGroupParams params)`	创建超级群用户组（IDL rev21 C17）
`listUserGroups`	`listUserGroups(String groupId)`	超级群用户组列表（IDL rev21 C17）
`getUserGroupsByUser`	`getUserGroupsByUser(String userId, {SupergroupChannelOptions? options})`	查询某用户所在的所有用户组（IDL rev21 C17）

功能指南：创建群组、群成员、群管理、超级群频道与用户组

聊天室（5）

方法	签名（本平台绑定）	说明
`createChatroom`	`createChatroom({String? chatroomId, required String name, String? owner})`	创建聊天室（客户端能力）
`joinChatroom`	`joinChatroom(String chatroomId)`	加入聊天室：发送 chatroom_join，收到 chatroom_joined
`leaveChatroom`	`leaveChatroom(String chatroomId)`	离开聊天室
`getChatroomInfo`	`getChatroomInfo(String chatroomId)`	聊天室信息（含在线数）
`getChatroomMembers`	`getChatroomMembers(String chatroomId, {int offset, int limit})`	聊天室在线成员列表

功能指南：加入与退出、聊天室信息

系统通知（1）

方法	签名（本平台绑定）	说明
`getSystemMessages`	`getSystemMessages({int limit, int? beforeSeq})`	系统通知历史（会话 conversationType=SYSTEM，targetId='system'）

功能指南：系统通知

文件上传（1）

方法	签名（本平台绑定）	说明
`uploadFile`	`uploadFile(List<int> data, String name, {String? mime})`	上传文件（<=20MB），返回可用于图片/文件/语音消息的 url

功能指南：文件上传

详细成员说明

连接与监听（7）

RCIMIWEngine.create(String appKey, RCIMIWEngineOptions options)

自 1.0.0本地（无 IO）幂等

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

参数

参数	类型	说明
`options`	`{appkey:string, serverUrl?:string, timeoutMs?:uint32, transport?:any}`	可选参数对象

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

示例

final engine = await RCIMIWEngine.create(
  '<appkey>',
  RCIMIWEngineOptions.create(naviServer: 'http://127.0.0.1:8080'),
);

connect(String token, int timeout, {RCIMIWConnectCallback? callback})

自 1.0.0长连接（WebSocket）

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

参数

参数	类型	说明
`token`	`string`	见类型定义

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

示例

final result = await engine.connect(<token>, 10);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

disconnect(bool receivePush)

自 1.0.0长连接（WebSocket）幂等

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

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

示例

engine.disconnect(false);

getConnectionStatus()

自 1.0.0本地（无 IO）

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

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

示例

final value = engine.getConnectionStatus();
print(value);

getCurrentUserId()

自 1.0.0本地（无 IO）

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

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

示例

final value = engine.getCurrentUserId();
print(value);

addEventListener(String event, void Function(Object?) handler)

自 1.0.0本地（无 IO）幂等

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

参数

参数	类型	说明
`event`	`string`	事件名，取值见 EventType
`handler`	`function`	事件处理函数（注册与移除需传同一引用）

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

示例

void onEvent(dynamic payload) {
  print(payload);
}

engine.addEventListener(RongIMEvents.MESSAGES, onEvent);

removeEventListener(String event, void Function(Object?) handler)

自 1.0.0本地（无 IO）幂等

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

参数

参数	类型	说明
`event`	`string`	事件名，取值见 EventType
`handler`	`function`	事件处理函数（注册与移除需传同一引用）

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

示例

void onEvent(dynamic payload) {
  print(payload);
}

engine.addEventListener(RongIMEvents.MESSAGES, onEvent);

消息（26）

sendMessage(int conversationType, String targetId, MessageContent content, {MessageOptions? options})

自 1.0.0长连接（WebSocket）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`content`	`Content`	消息内容体，字段见 MessageContent
`options`	`{clientMsgId?:string, channelId?:string}`	可选参数对象（可选）

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

示例

final result = await engine.sendMessage(RongIMConversationType.PRIVATE, 'user_001', TextContent('Hello, NI PaaS!'));
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

sendTextMessage(int conversationType, String targetId, String text, {MessageOptions? options})

自 1.0.0长连接（WebSocket）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`text`	`string`	文本消息内容（非空，序列化后 ≤ 5KB）
`options`	`{clientMsgId?:string, mentionedInfo?:MentionedInfo, quote?:Quote, channelId?:string}`	可选参数对象（可选）

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

示例

final result = await engine.sendTextMessage(RongIMConversationType.PRIVATE, 'user_001', 'Hello, NI PaaS!');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

sendImageMessage(int conversationType, String targetId, ImageContent content, {MessageOptions? options})

自 1.0.0长连接（WebSocket）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`content`	`{url:string,width?:uint32,height?:uint32,size?:uint64}`	消息内容体，字段见 MessageContent
`options`	`{clientMsgId?:string, channelId?:string}`	可选参数对象（可选）

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

示例

final result = await engine.sendImageMessage(RongIMConversationType.PRIVATE, 'user_001', TextContent('Hello, NI PaaS!'));
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

sendFileMessage(int conversationType, String targetId, FileContent content, {MessageOptions? options})

自 1.0.0长连接（WebSocket）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`content`	`{url:string,name:string,size?:uint64,mime?:string}`	消息内容体，字段见 MessageContent
`options`	`{clientMsgId?:string, channelId?:string}`	可选参数对象（可选）

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

示例

final result = await engine.sendFileMessage(RongIMConversationType.PRIVATE, 'user_001', TextContent('Hello, NI PaaS!'));
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

sendVoiceMessage(int conversationType, String targetId, VoiceContent content, {MessageOptions? options})

自 1.0.0长连接（WebSocket）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`content`	`{url:string,duration:uint32}`	消息内容体，字段见 MessageContent
`options`	`{clientMsgId?:string, channelId?:string}`	可选参数对象（可选）

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

示例

final result = await engine.sendVoiceMessage(RongIMConversationType.PRIVATE, 'user_001', TextContent('Hello, NI PaaS!'));
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

sendLocationMessage(int conversationType, String targetId, LocationContent content, {MessageOptions? options})

自 1.0.0长连接（WebSocket）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`content`	`{latitude:double,longitude:double,address?:string}`	消息内容体，字段见 MessageContent
`options`	`{clientMsgId?:string, channelId?:string}`	可选参数对象（可选）

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

示例

final result = await engine.sendLocationMessage(RongIMConversationType.PRIVATE, 'user_001', TextContent('Hello, NI PaaS!'));
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

sendTypingStatus(int conversationType, String targetId, bool typing)

自 1.0.0长连接（WebSocket）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`typing`	`bool`	true=正在输入，false=停止输入

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

示例

engine.sendTypingStatus(RongIMConversationType.PRIVATE, 'user_001', true);

recallMessage(String messageId)

自 1.0.0长连接（WebSocket）

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

参数

参数	类型	说明
`messageId`	`string`	消息 ID（服务端生成的 messageId）

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

示例

final result = await engine.recallMessage('msg_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

sendReadReceipt(int conversationType, String targetId, List<String> messageIds)

自 1.0.0长连接（WebSocket）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`messageIds`	`string[]`	消息 ID 列表

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

示例

final result = await engine.sendReadReceipt(RongIMConversationType.PRIVATE, 'user_001', ['msg_001']);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getMessageReadCount(String messageId)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`messageId`	`string`	消息 ID（服务端生成的 messageId）

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

示例

final result = await engine.getMessageReadCount('msg_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getMessageReadUsers(String messageId, {int offset, int limit})

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`messageId`	`string`	消息 ID（服务端生成的 messageId）
`options`	`{offset?:uint32, limit?:uint32}`	可选参数对象（可选）

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

示例

final result = await engine.getMessageReadUsers('msg_001', <String, dynamic>{'int offset': null, 'int': null});
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getMessageReadDetail(String messageId, {int offset, int limit, String? filter})

自 1.7.0REST（HTTP）

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

参数

参数	类型	说明
`messageId`	`string`	消息 ID（服务端生成的 messageId）
`options`	`{offset?:uint32, limit?:uint32, filter?:string}`	可选参数对象（可选）

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

示例

final result = await engine.getMessageReadDetail('msg_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

searchMessages({required String keyword, int limit})

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`options`	`{keyword:string, limit?:uint32}`	可选参数对象

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

示例

final result = await engine.searchMessages(<String, dynamic>{'required String keyword': null, 'int': null});
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

updateMessageExpansion(String messageId, Map<String, String> expansion)

自 1.1.0REST（HTTP）

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

参数

参数	类型	说明
`messageId`	`string`	消息 ID（服务端生成的 messageId）
`expansion`	`Record<string,string>`	见类型定义

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

示例

final result = await engine.updateMessageExpansion('msg_001', null, null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

removeMessageExpansion(String messageId, List<String> keys)

自 1.1.0REST（HTTP）

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

参数

参数	类型	说明
`messageId`	`string`	消息 ID（服务端生成的 messageId）
`keys`	`string[]`	见类型定义

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

示例

final result = await engine.removeMessageExpansion('msg_001', null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

addMessageReaction(int conversationType, String targetId, String messageId, String reactionId)

自 1.1.0REST（HTTP）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`messageId`	`string`	消息 ID（服务端生成的 messageId）
`reactionId`	`string`	见类型定义
`options`	`{pushConfig?:object}`	可选参数对象（可选）

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

示例

final result = await engine.addMessageReaction(RongIMConversationType.PRIVATE, 'user_001', 'msg_001', null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

removeMessageReaction(int conversationType, String targetId, String messageId, String reactionId)

自 1.1.0REST（HTTP）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`messageId`	`string`	消息 ID（服务端生成的 messageId）
`reactionId`	`string`	见类型定义

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

示例

final result = await engine.removeMessageReaction(RongIMConversationType.PRIVATE, 'user_001', 'msg_001', null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

batchGetMessageReactionSummaries(int conversationType, String targetId, List<String> messageIds)

自 1.1.0REST（HTTP）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`messageIds`	`string[]`	消息 ID 列表

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

示例

final result = await engine.batchGetMessageReactionSummaries(RongIMConversationType.PRIVATE, 'user_001', ['msg_001']);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getMessageReactions(int conversationType, String targetId, String messageId, {int? count, String? pageToken})

自 1.1.0REST（HTTP）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`messageId`	`string`	消息 ID（服务端生成的 messageId）
`options`	`{count?:uint32, pageToken?:string}`	可选参数对象（可选）

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

示例

final result = await engine.getMessageReactions(RongIMConversationType.PRIVATE, 'user_001', 'msg_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getMessageReactionUsers(int conversationType, String targetId, String messageId, String reactionId, {int? count, String? pageToken})

自 1.1.0REST（HTTP）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`messageId`	`string`	消息 ID（服务端生成的 messageId）
`reactionId`	`string`	见类型定义
`options`	`{count?:uint32, pageToken?:string}`	可选参数对象（可选）

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

示例

final result = await engine.getMessageReactionUsers(RongIMConversationType.PRIVATE, 'user_001', 'msg_001', null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

startStreamMessage(int conversationType, String targetId, {StartStreamMessageOptions? options})

自 1.2.0REST（HTTP）

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

参数

参数	类型	说明
`params`	`{conversationType:ConversationType, targetId:string, content?:Content}`	见类型定义

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

示例

final result = await engine.startStreamMessage(RongIMConversationType.PRIVATE, 'user_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

appendStreamMessage(String streamId, String delta, {AppendStreamMessageOptions? options})

自 1.2.0REST（HTTP）

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

参数

参数	类型	说明
`streamId`	`string`	见类型定义
`delta`	`string`	见类型定义
`options`	`{seq?:uint32}`	可选参数对象（可选）

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

示例

final result = await engine.appendStreamMessage(null, null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

completeStreamMessage(String streamId)

自 1.2.0REST（HTTP）

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

参数

参数	类型	说明
`streamId`	`string`	见类型定义

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

示例

final result = await engine.completeStreamMessage(null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getStreamMessage(String streamId)

自 1.2.0REST（HTTP）幂等

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

参数

参数	类型	说明
`streamId`	`string`	见类型定义

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

示例

final result = await engine.getStreamMessage(null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getMessageExpansion(String messageId)

自 1.3.0REST（HTTP）幂等

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

参数

参数	类型	说明
`messageId`	`string`	消息 ID（服务端生成的 messageId）

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

示例

final result = await engine.getMessageExpansion('msg_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

combineMessages(List<Message> messages, {CombineMessagesOptions? options})

自 1.3.0本地（无 IO）幂等

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

参数

参数	类型	说明
`messages`	`Message[]`	见类型定义
`options`	`{title?:string, senderNames?:Record<string,string>, textMaxChars?:uint32}`	可选参数对象（可选）

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

示例

final result = await engine.combineMessages(null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

会话（22）

getConversationList()

自 1.0.0REST（HTTP）

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

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

示例

final result = await engine.getConversationList();
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getConversation(int conversationType, String targetId)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId

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

示例

final result = await engine.getConversation(RongIMConversationType.PRIVATE, 'user_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getHistoryMessages(int conversationType, String targetId, {int limit, int? beforeSeq, String? channelId})

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`options`	`{limit?:uint32, beforeSeq?:uint64, channelId?:string}`	可选参数对象（可选）

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

示例

final result = await engine.getHistoryMessages(RongIMConversationType.PRIVATE, 'user_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

clearUnreadCount(int conversationType, String targetId)

自 1.0.0长连接（WebSocket）幂等

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId

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

示例

engine.clearUnreadCount(RongIMConversationType.PRIVATE, 'user_001');

setConversationToTop(int conversationType, String targetId, bool isTop)

自 1.0.0REST（HTTP）幂等

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`isTop`	`bool`	true=置顶，false=取消置顶

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

示例

engine.setConversationToTop(RongIMConversationType.PRIVATE, 'user_001', true);

saveTextMessageDraft(int conversationType, String targetId, String draft)

自 1.0.0REST（HTTP）幂等

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`draft`	`string`	草稿文本

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

示例

engine.saveTextMessageDraft(RongIMConversationType.PRIVATE, 'user_001', '明天见');

getTextMessageDraft(int conversationType, String targetId)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId

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

示例

final result = await engine.getTextMessageDraft(RongIMConversationType.PRIVATE, 'user_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

clearTextMessageDraft(int conversationType, String targetId)

自 1.0.0REST（HTTP）幂等

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId

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

示例

engine.clearTextMessageDraft(RongIMConversationType.PRIVATE, 'user_001');

setConversationNotificationLevel(int conversationType, String targetId, int level)

自 1.0.0REST（HTTP）幂等

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`level`	`NotificationLevel`	提醒级别，取值见 NotificationLevel

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

示例

engine.setConversationNotificationLevel(RongIMConversationType.PRIVATE, 'user_001', 2);

createConversationTag(String tagName, {CreateConversationTagOptions? options})

自 1.2.0REST（HTTP）

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

参数

参数	类型	说明
`tagName`	`string`	见类型定义
`options`	`{tagId?:string}`	可选参数对象（可选）

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

示例

final result = await engine.createConversationTag(null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

updateConversationTag(String tagId, String tagName)

自 1.2.0REST（HTTP）幂等

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

参数

参数	类型	说明
`tagId`	`string`	见类型定义
`tagName`	`string`	见类型定义

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

示例

final result = await engine.updateConversationTag(null, null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

deleteConversationTag(String tagId)

自 1.2.0REST（HTTP）幂等

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

参数

参数	类型	说明
`tagId`	`string`	见类型定义

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

示例

final result = await engine.deleteConversationTag(null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getConversationTags()

自 1.2.0REST（HTTP）幂等

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

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

示例

final result = await engine.getConversationTags();
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

addConversationsToTag(String tagId, List<ConversationRef> conversations)

自 1.2.0REST（HTTP）幂等

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

参数

参数	类型	说明
`tagId`	`string`	见类型定义
`conversations`	`ConversationRef[]`	见类型定义

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

示例

final result = await engine.addConversationsToTag(null, null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

removeConversationsFromTag(String tagId, List<ConversationRef> conversations)

自 1.2.0REST（HTTP）幂等

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

参数

参数	类型	说明
`tagId`	`string`	见类型定义
`conversations`	`ConversationRef[]`	见类型定义

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

示例

final result = await engine.removeConversationsFromTag(null, null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getConversationsFromTagByPage(String tagId, {ConversationTagPageOptions? options})

自 1.2.0REST（HTTP）幂等

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

参数

参数	类型	说明
`tagId`	`string`	见类型定义
`options`	`{offset?:uint32, limit?:uint32}`	可选参数对象（可选）

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

示例

final result = await engine.getConversationsFromTagByPage(null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getTagsFromConversation(int conversationType, String targetId)

自 1.2.0REST（HTTP）幂等

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId

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

示例

final result = await engine.getTagsFromConversation(RongIMConversationType.PRIVATE, 'user_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getUnreadCountByTag(String tagId)

自 1.2.0REST（HTTP）幂等

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

参数

参数	类型	说明
`tagId`	`string`	见类型定义

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

示例

final result = await engine.getUnreadCountByTag(null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

setConversationToTopInTag(String tagId, int conversationType, String targetId, bool top)

自 1.2.0REST（HTTP）幂等

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

参数

参数	类型	说明
`tagId`	`string`	见类型定义
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId
`top`	`bool`	见类型定义

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

示例

final result = await engine.setConversationToTopInTag(null, RongIMConversationType.PRIVATE, 'user_001', true);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

deleteConversation(int conversationType, String targetId)

自 1.2.0REST（HTTP）幂等

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`targetId`	`string`	目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId

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

示例

final result = await engine.deleteConversation(RongIMConversationType.PRIVATE, 'user_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getConversationTypeNotification(int conversationType)

自 1.2.0REST（HTTP）幂等

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType

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

示例

final result = await engine.getConversationTypeNotification(RongIMConversationType.PRIVATE);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

setConversationTypeNotification(int conversationType, int level)

自 1.2.0REST（HTTP）幂等

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

参数

参数	类型	说明
`conversationType`	`ConversationType`	会话类型，取值见 ConversationType
`level`	`int`	提醒级别，取值见 NotificationLevel

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

示例

final result = await engine.setConversationTypeNotification(RongIMConversationType.PRIVATE, 2);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

用户（10）

getUserProfile(String userId)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`userId`	`string`	用户 ID

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

示例

final result = await engine.getUserProfile('user_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

updateMyUserProfile({String? name, String? avatarUrl})

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`profile`	`{name?:string, avatarUrl?:string}`	待更新的资料字段（name / avatarUrl）

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

示例

final result = await engine.updateMyUserProfile();
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getOnlineStatus(String userId)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`userId`	`string`	用户 ID

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

示例

final result = await engine.getOnlineStatus('user_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getOnlineStatusBatch(List<String> userIds)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`userIds`	`string[]`	用户 ID 列表

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

示例

final result = await engine.getOnlineStatusBatch(['user_001', 'user_002']);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

subscribePresence(List<String> userIds)

自 1.4.0REST（HTTP）幂等

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

参数

参数	类型	说明
`userIds`	`string[]`	用户 ID 列表

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

示例

final result = await engine.subscribePresence(['user_001', 'user_002']);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

unsubscribePresence(List<String> userIds)

自 1.4.0REST（HTTP）幂等

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

参数

参数	类型	说明
`userIds`	`string[]`	用户 ID 列表

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

示例

final result = await engine.unsubscribePresence(['user_001', 'user_002']);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getPresenceSubscriptions()

自 1.4.0REST（HTTP）幂等

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

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

示例

final result = await engine.getPresenceSubscriptions();
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

registerPushToken(RegisterPushTokenOptions options)

自 1.5.0REST（HTTP）幂等

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

参数

参数	类型	说明
`options`	`{platform:string, token:string, deviceId?:string, appVersion?:string}`	可选参数对象

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

示例

final result = await engine.registerPushToken(null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

unregisterPushToken(String tokenId)

自 1.5.0REST（HTTP）幂等

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

参数

参数	类型	说明
`tokenId`	`string`	见类型定义

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

示例

final result = await engine.unregisterPushToken(null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getPushTokens()

自 1.5.0REST（HTTP）幂等

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

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

示例

final result = await engine.getPushTokens();
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

好友与黑名单（11）

searchUsers(String keyword, {int limit})

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`keyword`	`string`	搜索关键字
`options`	`{limit?:uint32}`	可选参数对象（可选）

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

示例

final result = await engine.searchUsers('ni', <String, dynamic>{'int': null});
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

sendFriendRequest(String toUserId, {String? message})

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`toUserId`	`string`	接收方 userId
`message`	`string`	附言 / 消息摘要（可选）

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

示例

final result = await engine.sendFriendRequest('user_002');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getFriendRequests({String? type, String? status})

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`options`	`{type?:'incoming'\|'outgoing', status?:'pending'\|'all'}`	可选参数对象（可选）

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

示例

final result = await engine.getFriendRequests();
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

acceptFriendRequest(String requestId)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`requestId`	`string`	好友请求 ID（requestId）

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

示例

final result = await engine.acceptFriendRequest('request_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

rejectFriendRequest(String requestId)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`requestId`	`string`	好友请求 ID（requestId）

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

示例

final result = await engine.rejectFriendRequest('request_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getFriends()

自 1.0.0REST（HTTP）

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

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

示例

final result = await engine.getFriends();
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

deleteFriend(String friendId)

自 1.0.0REST（HTTP）幂等

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

参数

参数	类型	说明
`friendId`	`string`	好友 userId

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

示例

engine.deleteFriend('user_002');

setFriendRemark(String friendId, String remark)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`friendId`	`string`	好友 userId
`remark`	`string`	好友备注名

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

示例

engine.setFriendRemark('user_002', '同事');

getBlacklist()

自 1.0.0REST（HTTP）

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

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

示例

final result = await engine.getBlacklist();
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

addToBlacklist(String userId)

自 1.0.0REST（HTTP）幂等

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

参数

参数	类型	说明
`userId`	`string`	用户 ID

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

示例

engine.addToBlacklist('user_001');

removeFromBlacklist(String userId)

自 1.0.0REST（HTTP）幂等

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

参数

参数	类型	说明
`userId`	`string`	用户 ID

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

示例

engine.removeFromBlacklist('user_001');

群组（20）

createGroup(String name, List<String> memberIds, {String? groupId, String? owner, GroupOptions? options})

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`options`	`{groupId?:string, name:string, owner?:string, members?:string[], groupType?:GroupType, joinPolicy?:JoinPolicy, maxMembers?:int}`	可选参数对象

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

示例

final result = await engine.createGroup('sample.png', null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getGroupsInfo(List<String> groupIds)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`groupIds`	`string[]`	群组 ID 列表

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

示例

final result = await engine.getGroupsInfo(['group_001']);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getGroupMembers(String groupId)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`groupId`	`string`	群组 ID

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

示例

final result = await engine.getGroupMembers('group_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

addGroupMembers(String groupId, List<String> userIds)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`groupId`	`string`	群组 ID
`userIds`	`string[]`	用户 ID 列表

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

示例

final result = await engine.addGroupMembers('group_001', ['user_001', 'user_002']);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

removeGroupMembers(String groupId, List<String> userIds)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`groupId`	`string`	群组 ID
`userIds`	`string[]`	用户 ID 列表

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

示例

final result = await engine.removeGroupMembers('group_001', ['user_001', 'user_002']);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

quitGroup(String groupId)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`groupId`	`string`	群组 ID

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

示例

engine.quitGroup('group_001');

updateGroupName(String groupId, String name)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`groupId`	`string`	群组 ID
`name`	`string`	名称（群名称 / 文件名等）

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

示例

final result = await engine.updateGroupName('group_001', 'sample.png');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

updateGroupNotice(String groupId, String notice)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`groupId`	`string`	群组 ID
`notice`	`string`	群公告

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

示例

final result = await engine.updateGroupNotice('group_001', '欢迎加入群聊');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

transferGroupOwner(String groupId, String newOwner)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`groupId`	`string`	群组 ID
`newOwner`	`string`	新群主 userId

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

示例

final result = await engine.transferGroupOwner('group_001', 'user_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

addGroupAdmin(String groupId, String userId)

自 1.0.0REST（HTTP）幂等

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

参数

参数	类型	说明
`groupId`	`string`	群组 ID
`userId`	`string`	用户 ID

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

示例

final result = await engine.addGroupAdmin('group_001', 'user_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

removeGroupAdmin(String groupId, String userId)

自 1.0.0REST（HTTP）幂等

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

参数

参数	类型	说明
`groupId`	`string`	群组 ID
`userId`	`string`	用户 ID

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

示例

final result = await engine.removeGroupAdmin('group_001', 'user_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

muteGroupMember(String groupId, String userId, int mutedUntil)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`groupId`	`string`	群组 ID
`userId`	`string`	用户 ID
`mutedUntil`	`uint64`	禁言截止时间（epoch ms）

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

示例

final result = await engine.muteGroupMember('group_001', 'user_001', Date.now() + 3_600_000);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

createSupergroupChannel(CreateSupergroupChannelParams params)

自 1.5.0REST（HTTP）

创建超级群频道（IDL rev21 C17；客户端 REST `POST /api/apps/{appkey}/supergroup/channels`）→ SupergroupChannel。channelId 服务端生成（`ch_`，应用内唯一）；joinPolicy 由 type 推导（public→open、private→invite），与之矛盾的显式取值 1001；仅群主/管理员可调用（否则 1003），群不存在 1005，单群 100 频道上限（超限 1015）。与 Open API `supergroup.channel.create` 共享状态。可能错误码：1001 参数错误、1002 Token 无效或已过期、1003 无权限、1005 群组不存在、1015 成员数量超出上限。

参数

参数	类型	说明
`params`	`{groupId:string, name:string, type:ChannelType, joinPolicy?:JoinPolicy}`	见类型定义

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

示例

final result = await engine.createSupergroupChannel(null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

listSupergroupChannels(String groupId)

自 1.5.0REST（HTTP）幂等

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

参数

参数	类型	说明
`groupId`	`string`	群组 ID

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

示例

final result = await engine.listSupergroupChannels('group_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

joinSupergroupChannel(String channelId, {SupergroupChannelOptions? options})

自 1.5.0REST（HTTP）幂等

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

参数

参数	类型	说明
`channelId`	`string`	见类型定义
`options`	`{groupId?:string}`	可选参数对象（可选）

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

示例

final result = await engine.joinSupergroupChannel(null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

leaveSupergroupChannel(String channelId, {SupergroupChannelOptions? options})

自 1.5.0REST（HTTP）幂等

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

参数

参数	类型	说明
`channelId`	`string`	见类型定义
`options`	`{groupId?:string}`	可选参数对象（可选）

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

示例

final result = await engine.leaveSupergroupChannel(null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

bindUserGroupToChannel(String channelId, String userGroupId, {SupergroupChannelOptions? options})

自 1.5.0REST（HTTP）幂等

把用户组绑定到频道（IDL rev21 C17；客户端 REST `POST .../supergroup/channels/{channelId}/usergroups`，幂等）→ `{groupId,channelId,userGroupId,bound:true,reverseIndexed}`。**双向维护** SupergroupChannel.userGroupIds 与 UserGroup.channelIds（rev21 修复 rev7 仅写频道侧导致的反向索引缺失），因此 `listUserGroups`/`getUserGroupsByUser` 的 channelIds 反查可用。仅群主/管理员（否则 1003）；频道/用户组不存在 1005。可能错误码：1001 参数错误、1002 Token 无效或已过期、1003 无权限、1005 群组不存在。该操作幂等：重复调用不会产生额外副作用。

参数

参数	类型	说明
`channelId`	`string`	见类型定义
`userGroupId`	`string`	见类型定义
`options`	`{groupId?:string}`	可选参数对象（可选）

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

示例

final result = await engine.bindUserGroupToChannel(null, null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

createUserGroup(CreateUserGroupParams params)

自 1.5.0REST（HTTP）

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

参数

参数	类型	说明
`params`	`{groupId:string, name:string, members?:string[]}`	见类型定义

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

示例

final result = await engine.createUserGroup(null);
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

listUserGroups(String groupId)

自 1.5.0REST（HTTP）幂等

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

参数

参数	类型	说明
`groupId`	`string`	群组 ID

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

示例

final result = await engine.listUserGroups('group_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getUserGroupsByUser(String userId, {SupergroupChannelOptions? options})

自 1.5.0REST（HTTP）幂等

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

参数

参数	类型	说明
`userId`	`string`	用户 ID
`options`	`{groupId?:string}`	可选参数对象（可选）

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

示例

final result = await engine.getUserGroupsByUser('user_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

聊天室（5）

createChatroom({String? chatroomId, required String name, String? owner})

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`options`	`{chatroomId?:string, name:string, owner?:string}`	可选参数对象

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

示例

final result = await engine.createChatroom();
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

joinChatroom(String chatroomId)

自 1.0.0长连接（WebSocket）幂等

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

参数

参数	类型	说明
`chatroomId`	`string`	聊天室 ID

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

示例

final result = await engine.joinChatroom('chatroom_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

leaveChatroom(String chatroomId)

自 1.0.0长连接（WebSocket）幂等

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

参数

参数	类型	说明
`chatroomId`	`string`	聊天室 ID

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

示例

engine.leaveChatroom('chatroom_001');

getChatroomInfo(String chatroomId)

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`chatroomId`	`string`	聊天室 ID

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

示例

final result = await engine.getChatroomInfo('chatroom_001');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

getChatroomMembers(String chatroomId, {int offset, int limit})

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`chatroomId`	`string`	聊天室 ID
`options`	`{offset?:uint32,limit?:uint32}`	可选参数对象（可选）

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

示例

final result = await engine.getChatroomMembers('chatroom_001', <String, dynamic>{'int offset': null, 'int': null});
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

系统通知（1）

getSystemMessages({int limit, int? beforeSeq})

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`options`	`{limit?:uint32,beforeSeq?:uint64}`	可选参数对象（可选）

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

示例

final result = await engine.getSystemMessages();
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

文件上传（1）

uploadFile(List<int> data, String name, {String? mime})

自 1.0.0REST（HTTP）

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

参数

参数	类型	说明
`data`	`bytes\|blob`	文件二进制内容
`name`	`string`	名称（群名称 / 文件名等）
`mime`	`string`	文件 MIME 类型（可选）

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

示例

final result = await engine.uploadFile(new Uint8Array([1, 2, 3]), 'sample.png');
if (result.code != 0) {
  print(result.code);
  print(result.msg);
}
print(result.data);

RCIMIWEngine 类（Flutter IMLib）

类继承图​

类说明​

概要​

连接与监听（7）​

消息（26）​

会话（22）​

用户（10）​

好友与黑名单（11）​

群组（20）​

聊天室（5）​

系统通知（1）​

文件上传（1）​

详细成员说明​

连接与监听（7）​

消息（26）​

会话（22）​

用户（10）​

好友与黑名单（11）​

群组（20）​

聊天室（5）​

系统通知（1）​

文件上传（1）​

相关链接​

类继承图

类说明

概要

连接与监听（7）

消息（26）

会话（22）

用户（10）

好友与黑名单（11）

群组（20）

聊天室（5）

系统通知（1）

文件上传（1）

详细成员说明

连接与监听（7）

消息（26）

会话（22）

用户（10）

好友与黑名单（11）

群组（20）

聊天室（5）

系统通知（1）

文件上传（1）

相关链接