历史消息

云信支持在客户端本地与云端存储历史消息，供后续查询。

本地历史消息

分页查询本地历史消息

SDK 提供了一个根据锚点查询本地消息历史记录的接口，根据提供的方向 (direct)，查询比 anchor(锚点消息) 更老 (QUERY_OLD) 或更新 (QUERY_NEW) 的最靠近 anchor 的 limit 条数据。结果使用 time 作为排序字段，按照时间戳从小到大。

• API 原型

dart /// 根据锚点和方向从本地消息数据库中查询消息历史。
 /// 根据提供的方向(direct)，查询比anchor更老（QUERY_OLD）或更新（QUERY_NEW）的最靠近anchor的limit条数据。
 /// 结果使用time作为排序字段。
 /// 注意：查询结果不包含锚点。
Future<NIMResult<List<NIMMessage>>> queryMessageListEx(
      NIMMessage anchor, QueryDirection direction, int limit);

• 参数说明

参数	类型	说明
anchor	NIMMessage	查询锚点
direction	QueryDirection	查询方向
limit	int	查询结果的条数限制

anchor参数表示查询锚点，也就是作为查询起点的那条消息，查询结果不包含锚点。不能设置为 null。

当进行首次查询时可以使用MessageBuilder.createEmptyMessage(...)方法生成空消息作为锚点。如要查询与 accid001 这个账号的点对点聊天消息记录，并将当前时间作为查询起点，则可以配置锚点：

createEmptyMessage 方法

dartvar result = await MessageBuilder.createEmptyMessage(
          sessionId: 'accid001', sessionType: NIMSessionType.p2p, timestamp: DateTime.now().millisecondsSinceEpoch);

direction表示查询方向，QueryDirection.QUERY_OLD表示比锚点更旧的消息，QueryDirection.QUERY_NEW表示比锚点更新的消息。

• 如果需要查询从 16:59:00 到 17:00:00 的消息，需要设置 direction 为QueryDirection.QUERY_OLD

• 如果需要查询从 17:00:00 到 17:01:00 的消息，需要设置 direction 为QueryDirection.QUERY_NEW

• 如果是首次查询，并且需要查询更旧的消息，此时创建的空消息只能穿当前时间戳

• 示例

dart/// 查询比 anchor时间更早的消息，查询20条，结果按照时间降序排列
final result = await NimCore.instance.messageService.queryMessageListEx(anchor,QueryDirection.QUERY_OLD,20);

查询最近一条消息

查询同指定会话的最近一条消息

dart///  [account] 对方的id/群id
///  [sessionType] 会话类型

Future<NIMResult<NIMMessage>> queryLastMessage(
      String account, NIMSessionType sessionType);

按消息 uuid 查询

• API 原型

dart /// 通过消息id批量获取NIMMessage
 ///  [uuids] 消息id列表
 ///  [sessionId] 会话id
 ///  [sessionType] 会话类型

Future<NIMResult<List<NIMMessage>>> queryMessageListByUuid(
      List<String> uuids,String sessionId,NIMSessionType sessionType);

• 示例

dart// 通过消息id批量获取NIMMessage
List<String> uuids = ['uuid1','uuid2'];
final result = await NimCore.instance.messageService.queryMessageListByUuid(uuidsList,sessionId,sessionType);

删除本地消息

删除单条消息

• API 介绍

指定一条消息进行本地删除

• API 原型

dart /// 删除一条消息记录
 ///  [message] 待删除的消息记录
 ///  [ignore] （Windows和macOS暂不支持，默认为false）true: 本地不记录清除操作; false: 本地记录清除操作
 ///  从云端拉取消息时，如果本地有删除该消息的操作记录，则该消息不会入库
 ///  删除标记会被清除标记覆盖

Future<void> deleteChattingHistory(NIMMessage message, bool ignore);

• 参数说明

参数	类型	说明
message	NIMMessage	待删除的消息记录
Ignore	bool	true: 本地不记录清除操作; false: 本地记录清除操作 从云端拉取消息时，如果本地有删除该消息的操作记录，则该消息不会入库 删除标记会被清除标记覆盖

• 示例

dart// 删除单条消息
await NimCore.instance.messageService.deleteChattingHistory(message,ignore);

删除多条消息

• API 介绍

指定多条消息进行本地删除

• API 原型

dart /// 删除多条消息记录（Windows和macOS暂不支持）
 ///
 ///  [msgList] 待删除的消息记录
 ///  [ignore] true: 本地不记录清除操作; false: 本地记录清除操作
 ///  从云端拉取消息时，如果本地有删除该消息的操作记录，则该消息不会入库
 ///  删除标记会被清除标记覆盖

  Future<void> deleteChattingHistoryList(
      List<NIMMessage> msgList, bool ignore);

• 参数说明

参数	类型	说明
msgList	List<NIMMessage>	待删除的消息记录
Ignore	bool	true: 本地不记录清除操作; false: 本地记录清除操作 从云端拉取消息时，如果本地有删除该消息的操作记录，则该消息不会入库 删除标记会被清除标记覆盖

• 示例

dart//  删除多条消息记录
await NimCore.instance.messageService.deleteChattingHistoryList(msgList,ignore);

删除指定会话内消息

• API 介绍

将某会话的所有消息从本地数据库中移除，且可以配置是否记录此次清除操作进数据库。若记录，则当从云端把该部分消息拉取下来后，将无法同步至本地数据库中。

dart /// 清除与指定用户的所有本地消息记录
 ///
 ///  [account]     聊天对象的云信 IM 账号，即 accid。
 ///  [sessionType] 聊天类型

Future<void> clearChattingHistory(
      String account, NIMSessionType sessionType);

• 参数说明

参数	类型	说明
account	String	聊天对象的云信 IM 账号，即 accid
sessionType	NIMSessionType	聊天对象的 ID，如果是单聊，为用户帐号，如果是群聊，为群组 ID

• 示例

dart// 本地记录清除操作
await NimCore.instance.messageService.clearChattingHistory(account,sessionType);

删除所有消息

SDK 支持删除数据库内所有消息。

dart/// 清空消息数据库的所有消息记录。
/// 可选择是否要同时清空本地最近会话列表。
/// 若最近联系人列表也被清空，会触发MsgServiceObserve.observeRecentContactDeleted(Observer, boolean)通知
///  [clearRecent] 是否同时清除本地最近会话列表

Future<void> clearMsgDatabase(bool clearRecent);

云端历史消息

云端历史消息查询

SDK 提供了查询云端消息历史的接口，查询以锚点 anchor 作为起始点（不包含锚点），根据 direction 参数，往前或往后查询由锚点到 toTime 之间的最多 limit 条消息。查询范围由 toTime 和 limit 共同决定，以先到为准。如果到 toTime 之间消息大于 limit 条，返回 limit 条记录，如果小于 limit 条，返回实际条数。当已经查询到头时，返回的结果列表的 size 可能会比 limit 小。

当进行首次查询时，锚点可以用使用 MessageBuilder#createEmptyMessage 接口生成。查询结果不包含锚点。该接口的最后一个参数可用于控制是否要将拉取到的消息记录保存到本地数据库，如果选择保存到了本地，再使用拉取本地消息记录的接口时，也能取到这些消息。

• API 原型

dart /// 从服务器拉取消息历史记录，可以指定查询的消息类型，结果不存本地消息数据库。
 /// <p>
 /// 以锚点anchor作为起始点（不包含锚点），根据direction参数，往前或往后查询由锚点到toTime之间的最多limit条消息。<br>
 /// 查询范围由toTime和limit共同决定，以先到为准。如果到toTime之间消息大于limit条，返回limit条记录，如果小于limit条，返回实际条数。
 /// 当已经查询到头时，返回的结果列表的size可能会比limit小
 ///
 ///  [anchor]    起始时间点的消息
 ///  [toTime]    结束时间点单位毫秒
 ///  [limit]     本次查询的消息条数上限(最多100条)
 ///  [direction] 查询方向，QUERY_OLD按结束时间点逆序查询，逆序排列；QUERY_NEW按起始时间点正序起查，正序排列
 ///  [msgTypes]  消息类型，数组。消息类型仅支持 0:文本，1:图片，2:语音，3:视频，4:地理位置，5:通知，6:文件，10:提示，100:自定义，其它为非法参数
 ///  [persist]   通过该接口获取的漫游消息记录，要不要保存到本地消息数据库。

  Future<NIMResult<List<NIMMessage>>> pullMessageHistoryExType(
      NIMMessage anchor,
      int toTime,
      int limit,
      QueryDirection direction,
      List<NIMMessageType> messageTypeList,
      bool persist);

• 参数说明

参数	类型	说明
anchor	NIMMessage	起始时间点的消息，不能为 null。 设置自定义锚点时，使用 MessageBuilder#createEmptyMessage 创建一个空对象即可
toTime	int	结束时间点单位毫秒
limit	int	本次查询的消息条数上限(最多 100 条)
direction	QueryDirection	查询方向，QUERY_OLD 按结束时间点逆序查询，逆序排列； QUERY_NEW 按起始时间点正序起查，正序排列
messageTypeList	List<NIMMessageType>	查询的消息类型。
persist	bool	通过该接口获取的漫游消息记录，要不要保存到本地消息数据库。

anchor参数表示查询锚点，也就是作为查询起点的那条消息，查询结果不包含锚点。不能设置为 null。

当进行首次查询时可以使用MessageBuilder.createEmptyMessage(...)方法生成空消息作为锚点。如要查询与 accid001 这个账号的点对点聊天消息记录，并将当前时间作为查询起点，则可以配置锚点：

dartvar result = await MessageBuilder.createEmptyMessage(
          sessionId: 'accid001', sessionType: NIMSessionType.p2p, timestamp: DateTime.now().millisecondsSinceEpoch);

direction表示查询方向，QueryDirection.QUERY_OLD表示比锚点更旧的消息，QueryDirection.QUERY_NEW表示比锚点更新的消息。

• 如果需要查询从 16:59:00 到 17:00:00 的消息，需要设置 direction 为QueryDirection.QUERY_OLD

• 如果需要查询从 17:00:00 到 17:01:00 的消息，需要设置 direction 为QueryDirection.QUERY_NEW

• 示例

dart// 服务端拉取历史消息100条
 int newTime = DateTime.now().millisecondsSinceEpoch;
    int oldTime = newTime - 1000 * 60 * 60; // 一小时前
    var anchorRes = await MessageBuilder.createEmptyMessage(sessionId: "testAccount", 
        sessionType: NIMSessionType.p2p, timestamp: newTime);
    var result = await NimCore.instance.messageService.pullMessageHistoryExType(anchorRes.data!,
        oldTime,limit,direction,mList,persist);

此外，还提供如下简单接口：

从服务器拉取消息历史记录。该接口查询方向为从后往前。以锚点 anchor 作为起始点（不包含锚点），往前查询最多 limit 条消息。 当已经查询到头时，返回的结果列表的 size 可能会比 limit 小。

dart///
///  [anchor] 查询锚点
///  [limit] 本次查询的消息条数上限(最多100条)
///  [persist] 通过该接口获取的历史消息记录，是否保存到本地消息数据库。
///
Future<NIMResult<List<NIMMessage>>> pullMessageHistory(
      NIMMessage anchor, int limit, bool persist);

删除云端历史消息

删除单会话云端历史消息

• API 原型

dart /// 清空历史消息
 ///
 ///  [sessionId]     用户帐号
 ///  [sessionType] 聊天类型
 ///  [sync] 是否同步给其他端
Future<void> clearServerHistory(String sessionId, NIMSessionType sessionType,
      bool sync);

• 参数说明

参数	类型	说明
sessionId	String	用户帐号
sessionType	NIMSessionType	聊天类型
sync	bool	是否同步给其他端

• 示例

dartawait NimCore.instance.messageService.clearServerHistory(sessionId,sessionType,sync);

单向删除单条云端历史消息

用户单向删除一条消息成功后，该账号下不再能从服务端拉取到该条消息。而且，本端登录此账号的其他端都会删除本地的该消息记录。其他账号不受到该操作影响。

• API 原型

dart///
 /// 删除本地某条消息，并同时单向删除服务端历史、漫游
 ///  [msg] 被单向删除的消息
 ///  [ext] 扩展字段

Future<NIMResult<int>> deleteMsgSelf(NIMMessage msg, String ext);

• 参数说明

参数	类型	说明
msg	NIMMessage	要被单向删除的消息
ext	String	扩展字段，选填

• 示例

dartvar result = await NimCore.instance.messageService.deleteMsgSelf(message,ext);

单向删除多条云端历史消息

• API 原型

dart///
 /// 单向删除多条消息，需要来自同一会话
 ///
 ///  [msgList] 被单向删除的消息列表
 ///  [ext] 扩展字段

Future<NIMResult<int>> deleteMsgListSelf(List<NIMMessage> msgList, String ext);

• 参数说明

参数	类型	说明
msgList	List<NIMMessage>	被单向删除的消息列表
ext	String	扩展字段

• 示例

dartvar result = await NimCore.instance.messageService.deleteMsgListSelf(mList,ext);

消息检索

SDK 当前支持关键字检索，可以通过 lucene 插件 进行检索，也可以通过 SDK 本身自带的检索功能。

本地消息检索

单会话检索

• API 介绍

SDK 提供了搜索单会话聊天记录的功能，搜索将返回：时间在 (startTime,endTime) 之间，消息类型为指定类型，且匹配搜索内容或消息发起者列表的一定数量的消息。

• API 原型

dart    /// 从本地消息数据库搜索消息历史。
    /// 搜索将返回：时间在 (startTime,endTime) 之间，消息类型为指定类型，且匹配搜索内容或消息发起者列表的一定数量的消息。
    ///
    ///  [sessionType] 会话类型
    ///  [sessionId] 聊天对象ID
    ///  [option] 搜索选项
Future<NIMResult<List<NIMMessage>>> searchMessage(NIMSessionType sessionType,
      String sessionId, MessageSearchOption searchOption);

其中 searchOption 为搜索选项，具体选项如下:

参数	类型	说明
startTime	int	起始时间,默认为 0
endTime	int	结束时间。默认为 0,表示最大时间戳。若自行设置，要保证 endTime 晚于 startTime。
limit	int	检索条数,默认 100 条,设置为 0 表示无条数限制
order	SearchOrderEnum	查询方向，默认为 SearchOrderEnum.DESC 表示从新消息往旧消息查，设置为 SearchOrderEnum.ASC 表示从旧消息往新消息查。无论查询方向如何，查询结果都按照旧消息到新消息的顺序排列。
messageTypes	List<NIMMessageType>	消息类型组合，默认只搜索文本类型, 只有在 allMessageTypes 为 false 时有效（Windows 和 macOS 暂支持列表中的第一个）
messageSubTypes	List<int>	查询的消息子类型组合
allMessageTypes	bool	搜索全部消息类型。默认为 false，当设置为 true 时，忽略 messageType，同时返回所有的消息类型消息。
searchContent	String	检索文本，如果需要搜索的消息类型为文本，会进行内容的匹配
fromIds	List<String>	消息发起者列表
enableContentTransfer	bool	将搜索文本中的正则特殊字符转义，默认 true（Windows 和 macOS 暂不支持）

• 示例

dart// 搜索『关键字』最新的100条消息
MessageSearchOption option = MessageSearchOption( limit: 100,searchContent: '测试')

 var result = await NimCore.instance.messageService.searchMessage(SessionTypeEnum.P2P,"testAccount",option);

全局检索

• API 介绍

SDK 提供了搜索全局聊天记录的功能，搜索将返回：时间在 (startTime,endTime) 之间，消息类型为指定类型，且匹配搜索内容或消息发起者列表的一定数量的消息。

• API 原型

dart  /// 从本地消息数据库全局搜索消息历史。
  /// 搜索将返回：时间在 (startTime,endTime) 之间，消息类型为指定类型，且匹配搜索内容或消息发起者列表的一定数量的消息。
  ///
  ///  [option] 搜索选项
 Future<NIMResult<List<NIMMessage>>> searchAllMessage(
      MessageSearchOption option);

其中 option 为搜索选项，MessageSearchOption 参考单会话检索 API

• 示例

dart// 搜索『测试』最新的100条消息
MessageSearchOption option = MessageSearchOption( limit: 100,searchContent: '测试')

var result = await NimCore.instance.messageService.searchAllMessage(searchOption);

单聊云端消息检索

• API 原型

dart /// 云端聊天记录关键词查询
 ///
 ///  [otherAccid] 对方的account
 ///  [fromTime] 起始时间点单位毫秒
 ///  [endTime] 结束时间点单位毫秒
 ///  [keyword] 搜索的关键词
 ///  [limit] 本次查询的消息条数上限(最多100条)
 ///  [reverse] 可选参数，不传默认false，true是表示反向查询(按时间正序起查，正序排列)，默认false表示按时间逆序起查，逆序排列
 Future<NIMResult<List<NIMMessage>>> searchRoamingMsg(
      String otherAccid,
      int fromTime,
      int endTime,
      String keyword,
      int limit,
      bool reverse);

• 参数说明

参数	类型	说明
otherAccid	String	对方的 account
fromTime	int	起始时间点单位毫秒
endTime	int	结束时间点单位毫秒
keyword	String	搜索的关键词
limit	int	本次查询的消息条数上限(最多 100 条)
reverse	bool	可选参数，不传默认 false，true 是表示反向查询(按时间正序起查，正序排列)，默认 false 表示按时间逆序起查，逆序排列

全文云端消息检索

• API 原型

dart /// 云端历史消息全文检索
 ///
 ///  [config] 配置

  Future<NIMResult<List<NIMMessage>>> searchCloudMessageHistory(
      MessageKeywordSearchConfig config);

• 参数说明

MessageKeywordSearchConfig 变量表

参数	类型	说明
keyword	String	关键词
fromTime	int	起始时间
toTime	int	终止时间
sessionLimit	int	会话数量上限
msgLimit	int	会话数量下限
asc	boolean	消息排序规则，默认 false
p2pList	List<String>	P2P 范围，要查询的会话范围是此参数与{@link MsgFullKeywordSearchConfig#teamList} 的并集
teamList	List<String>	群范围，如果只查询指定群中的消息，则输入这些群的 ID
otherAccid	String	Web必传字段，聊天对象的 IM 账号（accid）

• 示例

dartMessageKeywordSearchConfig config =MessageKeywordSearchConfig(keyword:'测试', startTime:'开始时间', endTime:'结束时间');

var result = await NimCore.instance.messageService.searchCloudMessageHistory(messageKeywordSearchConfig);