跳到主要内容

获取历史消息

开通服务​

从远端获取单群聊历史消息是指从融云服务端获取历史消息,该功能要求 App Key 已启用融云提供的单群聊消息云端存储服务。您可以在控制台 IM 服务的服务购买页面为当前使用的 App Key 开启服务。如果使用生产环境的 App Key,请注意仅 IM 旗舰版或 IM 尊享版可开通该服务。具体功能与费用以融云官方价格说明页面及计费说明文档为准。

请注意区分历史消息记录与离线消息?。融云针对单聊、群聊、系统消息默认提供最多 7 天(可调整)的离线消息缓存服务。客户端上线时 SDK 会自动收取离线期间的消息,无需 App 层调用 API。详见管理离线消息存储配置。

提示
  • 用户是否可以获取在加入群组之前的群聊历史消息取决于 App 在控制台的设置。您可以在需先按控制台内嵌指南嵌入到管理后台的 IM 服务功能配置页面(page_code: im_service_config)中,进入 单群聊 > 新用户获取加入群组前历史消息,启用此选项。启用此选项后,新入群用户可以获取在他们加入群组之前发送的所有群聊消息。如不启用,新入群用户只能看到他们入群后的群聊消息。
  • 默认情况下,用户不在群组中不能获取群组中的历史消息。如果您希望用户未在指定群组中时,也可以获取群组历史消息,可以在需先按控制台内嵌指南嵌入到管理后台的 IM 服务功能配置页面(page_code: im_service_config)中,进入 单群聊 > 用户不在群组时是否可以拉取历史消息,允许不在群组的用户也可以获取该群组的的历史消息。

获取历史消息​

开发者可以通过此接口来获取某个会话的历史消息。

方法​

Dart
Future<int> getMessages(RCIMIWConversationType type, String targetId, String? channelId, int sentTime, RCIMIWTimeOrder order, RCIMIWMessageOperationPolicy policy, int count, {IRCIMIWGetMessagesCallback? callback});

参数说明​

参数名参数类型描述
typeRCIMIWConversationType会话类型
targetIdString会话 ID
channelIdString频道 ID,仅支持超级群使用,其他会话类型传 null 即可。
sentTimeint当前消息时间戳
orderRCIMIWTimeOrder获取消息的方向。BEFORE:获取 sentTime 之前的消息 (时间递减),AFTER:获取 sentTime 之后的消息 (时间递增)
policyRCIMIWMessageOperationPolicy消息的加载策略。LOCAL:只加载本地,REMOTE:只加载远端,LOCAL_REMOTE:本地远端都加载
countint获取的消息数量,count的范围:大于 0 且小于等于 20
callbackIRCIMIWGetMessagesCallback事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数,仅触发 callback 回调。

返回值​

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

代码示例​

Dart
IRCIMIWGetMessagesCallback? callback = IRCIMIWGetMessagesCallback(
onSuccess: (List<RCIMIWMessage>? t, int? syncTimestamp, bool? hasMoreMsg) {
//...
}, onError: (int? code) {
//...
});

int? ret = await engine?.getMessages(type, targetId, channelId, sentTime, order, policy, count, callback:callback);

回调参数说明​

onSuccess 回调中包含以下参数:

参数名参数类型描述
tList<RCIMIWMessage>返回的消息列表
syncTimestampint下次拉取消息的时间戳锚点。建议在下一次调用时作为 sentTime 传入,以便连续获取历史消息
hasMoreMsgbool是否还有更多消息可拉取。true 表示还有更多消息,可继续拉取;false 表示已无更多消息

按日历查询本地消息​

您可以先调用 getMessageCountDetail,查询指定会话在日期范围内每天的本地消息数量,再根据结果中的 dateMs 调用 getMessages,读取用户所选日期的消息。此流程只访问本地数据库,不会从云端补取消息。

日期统计遵循以下规则:

  • 查询范围使用 Unix 毫秒时间戳,采用左闭右开区间 [startTime, endTime),即包含开始时间,不包含结束时间。单次查询最多覆盖 180 个自然日。
  • SDK 按查询时设备的系统时区划分自然日,即当天零点至次日零点。首尾日期只统计查询范围内的消息。
  • 结果按日期从新到旧排列,只包含有匹配消息的日期。没有匹配消息时,onSuccess 返回空列表。
  • dateMs 表示当天零点。如果开始时间不是零点,首日的 dateMs 可能早于 startTime。

查询每日消息数量​

接口原型:

Dart
Future<int> getMessageCountDetail(
RCIMIWConversationType type,
String targetId,
String? channelId,
RCIMIWMessageCountDetailOptions options, {
IRCIMIWGetMessageCountDetailCallback? callback,
});
参数名参数类型描述
typeRCIMIWConversationType会话类型。
targetIdString会话 ID。
channelIdString?超级群频道 ID,按原值精确匹配;其他会话传 null。此接口将 null 按空字符串处理,空字符串仅匹配空的频道 ID,不表示查询所有频道。
optionsRCIMIWMessageCountDetailOptions查询时间范围,使用 create(startTime: ..., endTime: ...) 构造。
callbackIRCIMIWGetMessageCountDetailCallback查询结果回调。成功时返回按日期从新到旧排列的列表,失败时返回错误码。

RCIMIWMessageCountDetailOptions 的字段如下。开始时间必须大于等于 0,结束时间必须大于开始时间;否则接口立即返回参数错误,不会触发回调。

字段类型描述
startTimeint?开始时间,包含在查询范围内。使用 Unix 毫秒时间戳,必须大于等于 0。
endTimeint?结束时间,不包含在查询范围内。使用 Unix 毫秒时间戳,必须大于 startTime。

返回的 Future<int> 表示本次接口调用的状态,查询结果通过回调获取:

  • 0:接口调用成功。查询成功时触发 onSuccess,失败时触发 onError。
  • 非 0:接口调用失败,不会触发回调。

以下示例查询当前月份每天的本地消息数量。engine 为已创建的引擎实例,type、targetId 和 channelId 用于指定待查询的会话和频道。

Dart
final now = DateTime.now();
final startTimeMs = DateTime(now.year, now.month, 1).millisecondsSinceEpoch;
final endTimeMs = DateTime(now.year, now.month + 1, 1).millisecondsSinceEpoch;
final options = RCIMIWMessageCountDetailOptions.create(
startTime: startTimeMs,
endTime: endTimeMs,
);
final code = await engine.getMessageCountDetail(
type,
targetId,
channelId,
options,
callback: IRCIMIWGetMessageCountDetailCallback(
onSuccess: (days) {
for (final day in days ?? <RCIMIWMessageCountDetail>[]) {
// dateMs 为查询时设备时区下当天零点的时间戳;messageCount 为该日查询范围内的消息数。
print('${day.dateMs}: ${day.messageCount}');
}
},
onError: (errorCode) => print('查询失败:$errorCode'),
),
);
if (code != 0) {
// 调用失败时不会触发上面的回调。
print('接口调用失败:$code');
}

RCIMIWMessageCountDetail 包含以下字段:

字段类型描述
dateMsint?查询时设备时区下当天零点的 Unix 毫秒时间戳。
messageCountint?该自然日内、且位于查询范围内的本地消息数量。

读取选定日期的消息​

用户选中日期后,调用 getMessages,并将查询策略设为 RCIMIWMessageOperationPolicy.local,读取该日的本地消息。

按以下步骤确定查询边界并处理结果:

  1. 将所选统计项的 dateMs 转换为本地 DateTime,再按日历计算次日零点。夏令时可能导致一天不足或超过 24 小时,因此不能直接加上固定的 24 小时。
  2. 将查询时间戳设为 dateMs - 1,方向设为 RCIMIWTimeOrder.after,使查询结果包含当天零点的消息。
  3. 按 [dayStartMs, nextDateMs) 过滤返回结果,即只保留发送时间大于等于当天零点、且小于次日零点的消息。

以下示例中的 selectedDay 是用户从日期统计结果中选中的项。

Dart
final dayStartMs = selectedDay.dateMs!;
final localDate = DateTime.fromMillisecondsSinceEpoch(dayStartMs);
final nextDateMs = DateTime(
localDate.year,
localDate.month,
localDate.day + 1,
).millisecondsSinceEpoch;

final code = await engine.getMessages(
type,
targetId,
channelId,
dayStartMs - 1,
RCIMIWTimeOrder.after,
RCIMIWMessageOperationPolicy.local,
20,
callback: IRCIMIWGetMessagesCallback(
onSuccess: (messages, syncTimestamp, hasMoreMsg) {
final dayMessages = List<RCIMIWMessage>.of(messages ?? [])
.where((message) {
final sentTime = message.sentTime;
return sentTime != null &&
sentTime >= dayStartMs &&
sentTime < nextDateMs;
})
.toList()
..sort((a, b) => (a.sentTime ?? 0).compareTo(b.sentTime ?? 0));
// 使用 dayMessages 更新所选日期的消息列表。
// 本地查询固定返回 syncTimestamp=0、hasMoreMsg=false,不能据此判断是否还有消息。
},
onError: (errorCode) => print('读取失败:$errorCode'),
),
);
if (code != 0) {
// 调用失败时不会触发上面的回调。
print('接口调用失败:$code');
}

上例只读取首批消息,getMessages 的 count 每次不能超过 20。当前 Flutter SDK 使用 RCIMIWMessageOperationPolicy.local 策略时,固定返回 syncTimestamp=0、hasMoreMsg=false。这两个值不能用于判断当天消息是否已全部读取,也不能用于继续分页。

若需读取更多消息,请按返回消息的 sentTime 继续查询,并始终按 [dayStartMs, nextDateMs) 过滤结果。仅依赖 sentTime 无法区分同一毫秒发送的多条消息,不能保证分页时不遗漏消息。

如果设备时区在查询后发生变化,请按新时区重新统计日期并读取消息,不要复用原有的 dateMs 或日期边界。

通过 messageId 获取消息​

开发者可以通过此接口来获取某条本地数据库的消息。

方法​

Dart
Future<int> getMessageById(int messageId, {IRCIMIWGetMessageCallback? callback});

参数说明​

参数名参数类型描述
messageIdint消息的 messageId,可在消息对象中获取
callbackIRCIMIWGetMessageCallback事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数,仅触发 callback 回调。

返回值​

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

代码示例​

Dart
IRCIMIWGetMessageCallback? callback = IRCIMIWGetMessageCallback(
onSuccess: (RCIMIWMessage? t) {
//...
}, onError: (int? code) {
//...
});

int? ret = await engine?.getMessageById(messageId, callback:callback);

通过 messageUId 获取消息​

开发者可以通过此接口来获取某条本地数据库的消息。

方法​

Dart
Future<int> getMessageByUId(String messageUId, {IRCIMIWGetMessageCallback? callback});

参数说明​

参数名参数类型描述
messageUIdString消息的 messageUid,可在消息对象中获取,且只有发送成功的消息才会有值。
callbackIRCIMIWGetMessageCallback事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数,仅触发 callback 回调。

返回值​

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

代码示例​

Dart
IRCIMIWGetMessageCallback? callback = IRCIMIWGetMessageCallback(
onSuccess: (RCIMIWMessage? t) {
//...
}, onError: (int? code) {
//...
});

int? ret = await engine?.getMessageByUId(messageUId, callback:callback);

按消息类型获取本地消息​

获取会话中指定类型的本地消息。

方法​

Dart
Future<int> getLocalMessagesByMessageTypes(RCIMIWConversationType type, String targetId, String? channelId, List<RCIMIWMessageType> messageTypes, int sentTime, RCIMIWTimeOrder order, int count, {IRCIMIWGetLocalMessagesByMessageTypesCallback? callback});

参数说明​

参数名参数类型描述
typeRCIMIWConversationType会话类型
targetIdString会话 ID
channelIdString消息所属会话的业务标识,仅支持超级群使用,其他会话类型传 null 即可。
messageTypesList<RCIMIWMessageType>消息类型列表
sentTimeint消息发送时间戳,0 表示最新的消息
orderRCIMIWTimeOrder获取消息的方向。BEFORE:获取 sentTime 之前的消息 (时间递减),AFTER:获取 sentTime 之后的消息 (时间递增)
countint获取的消息数量
callbackIRCIMIWGetLocalMessagesByMessageTypesCallback事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数,仅触发 callback 回调。

返回值​

返回值描述
Future<int>当次接口操作的状态码。0 代表调用成功 具体结果通过接口 callback 回调,非 0 代表当前接口调用操作失败,不会触发接口回调,详细错误参考错误码

代码示例​

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

int? ret = await engine?.getLocalMessagesByMessageTypes(type, targetId, channelId, messageTypes, sentTime, order, count, callback:callback);

根据时间获取前后消息​

在会话中获取指定消息的前后指定数量的消息。返回的消息列表中会包含指定的消息。消息列表时间顺序从新到旧。

方法​

Dart
Future<int> getMessagesAroundTime(RCIMIWConversationType type, String targetId, String? channelId, int sentTime, int beforeCount, int afterCount, {IRCIMIWGetMessagesAroundTimeCallback? callback});

参数说明​

参数名参数类型描述
typeRCIMIWConversationType会话类型
targetIdString会话 ID
channelIdString消息所属会话的业务标识,仅支持超级群使用,其他会话类型传 null 即可。
sentTimeint指定消息的发送时间,不能为 0。单位:毫秒
beforeCountint指定消息的前部分消息数量
afterCountint指定消息的后部分消息数量
callbackIRCIMIWGetMessagesAroundTimeCallback事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数,仅触发 callback 回调。

返回值​

返回值描述
Future<int>当次接口操作的状态码。0 代表调用成功 具体结果通过接口 callback 回调,非 0 代表当前接口调用操作失败,不会触发接口回调,详细错误参考错误码

代码示例​

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

int? ret = await engine?.getMessagesAroundTime(type, targetId, channelId, sentTime, beforeCount, afterCount, callback:callback);

回调方法​

  • onMessagesAroundTimeLoaded
Dart
Function(int? code, RCIMIWConversationType? type, String? targetId, String? channelId, int? sentTime, int? beforeCount, int? afterCount, List<RCIMIWMessage>? messages)? onMessagesAroundTimeLoaded;

参数说明

参数名参数类型描述
codeint接口回调的状态码,0 代表成功,非 0 代表出现异常
typeRCIMIWConversationType会话类型
targetIdString会话 ID
channelIdString消息所属会话的业务标识
sentTimeint指定消息的发送时间
beforeCountint指定消息的前部分消息数量
afterCountint指定消息的后部分消息数量
messagesList<RCIMIWMessage>获取到的消息集合

代码示例

Dart
engine?.onMessagesAroundTimeLoaded = (int? code, RCIMIWConversationType? type, String? targetId, String? channelId, int? sentTime, int? beforeCount, int? afterCount, List<RCIMIWMessage>? messages) {
//...
};