获取会话

客户端 SDK 会根据收发的消息在本地数据库中生成对应会话。您可以从本地数据库获取 SDK 生成的会话列表。

获取会话列表

通过以下接口分页获取 SDK 在本地数据库生成的会话列表。获取到的会话列表按照时间倒序排列，置顶会话会排在最前。

方法

Dart

Future<int> getConversations(List<RCIMIWConversationType> conversationTypes, String? channelId, int startTime, int count, {IRCIMIWGetConversationsCallback? callback});

参数说明

参数名	参数类型	描述
conversationTypes	List<RCIMIWConversationType>	会话类型
channelId	String	频道 ID，仅支持超级群使用，其他会话类型传 null 即可
startTime	int	时间戳（毫秒），获取小于此时间戳的会话，传 0 为查询最新数据。在分页获取会话时，传入回调结果中最后一条会话数据的 operationTime，来获取下一页数据。
count	int	查询的数量， 0 < count ≤ 50
callback	IRCIMIWGetConversationsCallback	获取会话列表事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数，仅触发 callback 回调。

返回值

返回值	描述
Future<int>	当次接口操作的状态码。0 代表接口调用成功，具体业务结果需要从接口回调获取；非 0 代表当前接口调用操作失败，不会触发接口回调。详细错误参考错误码。

代码示例

Dart

IRCIMIWGetConversationsCallback? callback = IRCIMIWGetConversationsCallback(
onSuccess: (List<RCIMIWConversation>? t) {
//...
},
onError: (int? code) {
//...
});

int? ret = await engine?.getConversations(conversationTypesInt, channelId, startTime, count, callback:callback);

按条件获取会话列表

通过 getConversationListByFilters 接口按会话类型、频道 ID 和未读状态获取本地会话列表，支持分页和置顶优先排序。

方法

Dart

Future<int> getConversationListByFilters(
  List<RCIMIWConversationTypeFilter> filters,
  RCIMIWConversationListOption? option, {
  IRCIMIWGetConversationsCallback? callback,
});

参数说明

参数名	参数类型	描述
filters	List<RCIMIWConversationTypeFilter>	会话类型和频道过滤条件列表，不能为空，最多支持 300 个条件。返回符合任一条件的会话。
option	RCIMIWConversationListOption?	分页、排序和未读状态筛选配置。传 null 时使用默认配置。
callback	IRCIMIWGetConversationsCallback?	获取会话列表事件回调。查询结果通过 onSuccess 返回，查询错误通过 onError 返回。

RCIMIWConversationTypeFilter

使用 RCIMIWConversationTypeFilter.create 创建过滤条件。

属性名	属性类型	描述
type	RCIMIWConversationType?	会话类型，必须指定有效的会话类型。
channelId	String?	频道 ID。空字符串表示默认频道；查询指定超级群频道时传该频道 ID。

备注

channelId 为 null 时，Android 按默认频道查询，iOS 保留原生 SDK 不按频道过滤的行为。查询默认频道时，建议显式传空字符串，以保证两端行为一致。

RCIMIWConversationListOption

使用 RCIMIWConversationListOption.create 创建查询配置。未设置的属性使用原生 SDK 默认值。

属性名	属性类型	描述
count	int?	每页获取数量，默认 20，取值范围为 1 至 300。
startTime	int?	起始时间戳，单位为毫秒，默认 0。获取该时间戳之前的会话，传 0 表示从最新会话开始。分页时使用上一页最后一条会话的 operationTime 获取下一页。
topPriority	bool?	是否优先返回置顶会话，默认 true。传 false 时按会话时间倒序排列。
unreadCountFilter	RCIMIWConversationUnreadCountFilter?	未读状态筛选条件，默认 RCIMIWConversationUnreadCountFilter.all。

RCIMIWConversationUnreadCountFilter

枚举值	描述
all	不按未读状态筛选，返回符合其他条件的全部会话。
unreadOnly	仅返回未读消息数大于 0 的会话。
mentionOnly	仅返回存在未读 @ 消息的会话，包括 @ 我的消息和 @ 所有人的消息。
noUnread	仅返回未读消息数等于 0 的会话。

返回值

返回值	描述
Future<int>	当次接口操作的状态码。0 代表接口调用成功，具体业务结果需要从接口回调获取；非 0 代表当前接口调用操作失败，不会触发接口回调。详细错误参考错误码。

代码示例

以下示例分页获取单聊和群聊中的未读会话。示例将 topPriority 设置为 false，按会话时间倒序分页。首次调用 loadNextPage() 获取最新一页，后续调用获取下一页；请在上一次查询结束后再发起下一次查询。

Dart

final filters = <RCIMIWConversationTypeFilter>[
  RCIMIWConversationTypeFilter.create(
    type: RCIMIWConversationType.private,
    channelId: '',
  ),
  RCIMIWConversationTypeFilter.create(
    type: RCIMIWConversationType.group,
    channelId: '',
  ),
];

const pageSize = 20;
int startTime = 0;
bool hasMore = true;

Future<void> loadNextPage() async {
  if (!hasMore) {
    return;
  }

  final option = RCIMIWConversationListOption.create(
    count: pageSize,
    startTime: startTime,
    topPriority: false,
    unreadCountFilter: RCIMIWConversationUnreadCountFilter.unreadOnly,
  );

  final callback = IRCIMIWGetConversationsCallback(
    onSuccess: (List<RCIMIWConversation>? conversations) {
      final page = conversations ?? <RCIMIWConversation>[];
      hasMore = page.length == pageSize;
      if (page.isNotEmpty) {
        startTime = page.last.operationTime ?? startTime;
      }
      // 将 page 中的会话追加到业务会话列表。
    },
    onError: (int? code) {
      // 处理查询失败，可使用当前 startTime 重试。
    },
  );

  final ret = await engine.getConversationListByFilters(
    filters,
    option,
    callback: callback,
  );
  if (ret != 0) {
    // 处理接口调用失败，此时不会触发 callback。
  }
}

await loadNextPage();

实际返回数量小于 count 时表示已取完符合条件的数据。切换筛选条件时，应将 startTime 重置为 0，并重新获取列表。如不需要按未读状态筛选，可不设置 unreadCountFilter，或设置为 RCIMIWConversationUnreadCountFilter.all。

获取指定会话

获取某个会话的详细信息。

方法

Dart

Future<int> getConversation(RCIMIWConversationType type, String targetId, String? channelId, {IRCIMIWGetConversationCallback? callback});

参数说明

参数名	参数类型	描述
type	RCIMIWConversationType	会话类型
targetId	String	会话 ID
channelId	String	频道 ID，仅支持超级群使用，其他会话类型传 null 即可
callback	IRCIMIWGetConversationCallback	获取会话事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数，仅触发 callback 回调。

返回值

返回值	描述
Future<int>	当次接口操作的状态码。0 代表接口调用成功，具体业务结果需要从接口回调获取；非 0 代表当前接口调用操作失败，不会触发接口回调。详细错误参考错误码。

代码示例

Dart

IRCIMIWGetConversationCallback? callback = IRCIMIWGetConversationCallback(
onSuccess: (RCIMIWConversation? t) {
//...
}, onError: (int? code) {
//...
});

int? ret = await engine?.getConversation(type, targetId, channelId, callback:callback);

同步服务端会话信息到本地

提示

SDK 从 5.32.1 版本开始提供该接口。您可提交工单申请开通远程会话列表同步功能。

针对更换设备登录或卸载重新安装应用的情况下，使用 getRemoteConversationList() 接口可以将服务端的会话信息同步到本地。该接口只触发拉取操作，会话同步完成后，通过 onRemoteConversationListSynced 监听同步结果。

方法

Dart

Future<int> getRemoteConversationList({IRCIMIWOperationCallback? callback});

参数说明

参数名	参数类型	描述
callback	IRCIMIWOperationCallback	操作回调

返回值

返回值	描述
Future<int>	当次接口操作的状态码。0 代表接口调用成功，具体业务结果需要从接口回调获取；非 0 代表当前接口调用操作失败，不会触发接口回调。详细错误参考错误码。

代码示例

Dart

// 发起拉取远端会话请求
IRCIMIWOperationCallback? callback = IRCIMIWOperationCallback(
onSuccess: () {
//...
},
onError: (int? code) {
//...
});

int? ret = await engine?.getRemoteConversationList(callback: callback);

Dart

// 监听远端会话列表同步完成
engine?.onRemoteConversationListSynced = (int? code) {
//...
};

获取未读列表

获取指定类型的含有未读消息的会话列表，支持单聊、群聊、系统会话。获取到的会话列表按照时间倒序排列，置顶会话会排在最前。

方法

Dart

Future<int> getUnreadConversations(List<RCIMIWConversationType> conversationTypes, {IRCIMIWGetUnreadConversationsCallback? callback});

参数说明

参数名	参数类型	描述
conversationTypes	List<RCIMIWConversationType>	支持单聊、群聊、系统会话
callback	IRCIMIWGetUnreadConversationsCallback	获取会话列表事件回调。

返回值

返回值	描述
Future<int>	当次接口操作的状态码。0 代表接口调用成功，具体业务结果需要从接口回调获取；非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码。

代码示例

Dart

IRCIMIWGetUnreadConversationsCallback? callback = IRCIMIWGetUnreadConversationsCallback(
onSuccess: (List<RCIMIWConversation>? t) {
//...
},
onError: (int? code) {
//...
});

int? ret = await engine?.getUnreadConversations(conversationTypesInt, callback:callback);

常见问题

Q1: 当用户卸载重新安装后发现会话列表为空或者部分会话丢失

A1: 由于会话列表是从本地数据库获取的,是在 SDK 内部数据库存储的,所以当用户在卸载的时候会删除本地数据库,导致重新安装后会话列表为空。而会出现部分会话的原因是因为开启了消息补偿功能,具体操作是在需先按控制台内嵌指南嵌入到管理后台的 IM 服务功能配置页面（page_code: im_service_config）中，进入 多端 > 多设备消息同步，开启该功能。这个功能里默认涵盖了当天(当天 0 点)的消息补偿,所以当用户在新设备登录会触发消息补偿功能,从而获取到部分会话,造成部分会话丢失的错觉。如果想要更多天的消息补偿,可提交工单修改,最多支持 7 天。设置时间过长,当单用户消息量超大时,可能会因为补偿消息量过大,造成端上处理压力的问题。