功能描述

拉取历史消息的 API 在类 TencentImSDKPlugin.v2TIMManager.getMessageManager() 中。
除了支持单聊、群聊历史消息的拉取外，还提供了高级接口以支持按指定方向拉取、按指定起点和指定时间范围拉取。
除了支持单独拉取本地历史消息外，还支持拉取云端历史消息。

说明：

在拉取云端历史消息时，如果检测到网络异常，SDK 会返回本地存储的历史消息。

本地存储的历史消息无时间显示，但云端存储的历史消息有存储时长的限制：

体验版：免费存储 7 天，不支持延长
专业版：免费存储 7 天，支持延长
旗舰版：免费存储 30 条，支持延长

说明：

延长历史消息存储时长是增值服务，您可以登录即时通信 IM 控制台修改相关配置，具体计费说明请参加增值服务资费。
富媒体消息（图片、文件、语音等）对应的文件存储时长，与历史消息存储时长保持一致。

拉取单聊历史消息

您可以调用接口 getC2CHistoryMessageList 获取单聊历史消息。在网络正常的情况下会拉取最新的云端数据。如果网络出现异常，SDK 会返回本地存储的历史消息。如果您仅仅想拉取本地历史消息，可以参考高级接口。

本接口支持分页拉取，参考：分页拉取。

示例代码如下：

// 拉取单聊历史消息
// 首次拉取，lastMsgID 设置为 null
// 再次拉取时，lastMsgID 可以使用返回的消息列表中的最后一条消息的id
TencentImSDKPlugin.v2TIMManager.getMessageManager().getC2CHistoryMessageList(
        userID: "userId",
        count: 10,
        lastMsgID: null,
);

拉取群聊历史消息

您可以调用接口 getGroupHistoryMessageList 获取群聊历史消息。在网络正常的情况下会拉取最新的云端数据。如果网络出现异常，SDK 会返回本地存储的历史消息。如果您仅仅想拉取本地历史消息，可以参考高级接口。

本接口支持分页拉取，参考：分页拉取。

注意：

只有会议群（Meeting）才能拉取到进群前的历史消息，更多关于群消息的限制，详见消息能力差异。
直播群（AVChatRoom）消息不存云端漫游和本地数据库，调用这个接口无效。

示例代码如下：

// 拉取群聊历史消息
// 首次拉取，lastMsgID 设置为 null
// 再次拉取时，lastMsgID 可以使用返回的消息列表中的最后一条消息id
TencentImSDKPlugin.v2TIMManager
      .getMessageManager()
      .getGroupHistoryMessageList(
        groupID: "groupID",
        count: 10,
        lastMsgID: null,
      );

高级功能

高级接口

如果以上的普通接口无法满足您对拉取历史消息的需求，我们还提供了高级接口 getHistoryMessageList。

该接口除了支持普通拉取单聊、群聊历史消息外，还支持以下高级特性：

支持设置拉取消息的位置：从本地拉取、从云端拉取。
支持按照指定的方向拉取：往消息时间更老的方向拉取、往消息时间更新的方向拉取。
支持拉取本地指定的消息类型：文本、图片、语音、视频、文件、表情、群 tips 消息、合并消息、自定义消息等。

接口原型：

Future<V2TimValueCallback<List<V2TimMessage>>> getHistoryMessageList({
    HistoryMsgGetTypeEnum? getType =
        HistoryMsgGetTypeEnum.V2TIM_GET_LOCAL_OLDER_MSG,
    String? userID,
    String? groupID,
    int lastMsgSeq = -1,
    required int count,
    String? lastMsgID,
  }) async {
    return ImFlutterPlatform.instance.getHistoryMessageList(
        getType: getType!.index,
        userID: userID,
        count: count,
        lastMsgID: lastMsgID,
        groupID: groupID,
        lastMsgSeq: lastMsgSeq);
  }

参数说明：

参数	含义	单聊有效	群聊有效	是否必填	说明
getType	拉取消息的位置及方向，可以设置拉取本地/云端的更老/更新的消息	YES	YES	YES	当设置从云端拉取时，会将本地存储消息列表与云端存储消息列表合并后返回。如果无网络，则直接返回本地消息列表。
userID	拉取指定用户的单聊历史消息	YES	NO</font>	NO	拉取单聊消息，需要指定对方的 userID，此时 groupID 传空即可。
groupID	拉取指定群组的群聊历史消息	NO</font>	YES	NO	拉取单聊消息，需要指定群聊的 groupID，此时 userID 传空即可。
count	单次拉取的消息数量	YES	YES	YES	建议设置为 20，否则可能影响拉取速度
lastMsgID	最后一条消息，表示从哪条消息开始拉取历史消息	YES	YES	NO	1. 单聊和群聊中均能使用。 2. 设置 lastMsg 作为拉取的起点，返回的消息列表中不包含这条消息。 3. 如果设置为空，则使用会话的最新一条消息作为拉取起点。
lastMsgSeq	最后一条消息 seq，表示从哪条消息开始拉取历史消息	NO</font>	YES	NO	1. 仅能在群聊中使用该字段。 2. 设置 lastMsgSeq 作为拉取的起点，返回的消息列表中包含这条消息。 3. 如果同时指定了 lastMsg 和 lastMsgSeq，SDK 优先使用 lastMsg。 4. 如果均未指定 lastMsg 和 lastMsgSeq，拉取的起点取决于是否设置 getTimeBegin。设置了，则使用设置的范围作为起点；未设置，则使用最新消息作为起点。

分页拉取

拉取单聊历史消息、拉取群聊历史消息以及高级接口均可以按照相同的方式实现分页，即使用 lastMsg 和 count 来实现。

通过 lastMsg 和 count 来实现分页。第一次拉取时 lastMsg 可以设置为空，使用消息列表中返回来最后一条消息作为下一次拉取的 lastMsg 从而拉去下一页数据。
当 lastMsg 设置为空时，SDK 会默认从最新的消息开始返回。
当设置 lastMsg 后，返回的消息列表不包含设置的 lastMsg。
返回的消息列表中，越新的消息越靠前。

说明：

为了不影响历史消息拉取速度，建议分页时 count 设置为 20。
由于返回的消息列表会包含 lastMsgSeq 所对应的消息，所以在拉取群聊历史消息时，不建议使用 lastMsgSeq 来续拉。

仅拉取本地消息

通过设置 getType 来实现仅拉取本地消息：

getType 取值为 V2TIM_GET_LOCAL_OLDER_MSG 时，表示往时间更旧的方向，拉取本地存储的消息。
getType 取值为 V2TIM_GET_LOCAL_NEWER_MSG 时，表示往时间更新的方向，拉取本地存储的消息。

示例代码将演示：从最新的消息开始，往更老的方向，从本地数据库中拉取 20 条单聊消息。

TencentImSDKPlugin.v2TIMManager.getMessageManager().getHistoryMessageList(
        count: 10,
        getType: HistoryMsgGetTypeEnum.V2TIM_GET_LOCAL_OLDER_MSG,
        userID: "userID",
);

跳转到群 @ 消息后拉取

在群聊会话中，收到群 @ 消息后，一般需要通过点击群 @ 提示条，跳转到群 @ 消息的位置，并拉取附近的消息列表用于显示。由于群 @ 消息本身也需要显示，可以将 lastMsgSeq 设置成群 @ 消息的 sequence ，并使用高级接口来拉取。

示例代码将演示：点击群 @ 提示后，跳转到群 @ 消息，并拉取前后各 20 条消息用于展示。

// 获取群 @ 消息对应的的 sequence
int atSequence = 1081;

// 拉取群 @ 消息及之前的消息

  TencentImSDKPlugin.v2TIMManager.getMessageManager().getHistoryMessageList(
        count: 20, // 拉取 20 条
        getType: HistoryMsgGetTypeEnum.V2TIM_GET_CLOUD_OLDER_MSG, // 拉取比群 @ 消息更早的消息
        lastMsgSeq: atSequence,// 从群 @ 消息开始拉取，包括群 @ 消息
        groupID: "groupID" // 拉取群聊消息
      );



// 拉取群 @ 消息之后的消息
TencentImSDKPlugin.v2TIMManager.getMessageManager().getHistoryMessageList(
        count: 20, // 拉取 20 条
        getType: HistoryMsgGetTypeEnum.V2TIM_GET_CLOUD_NEWER_MSG, // 拉取比群 @ 消息更晚的消息
        lastMsgSeq: atSequence,// 从群 @ 消息开始拉取，包括群 @ 消息
        groupID: "groupID" // 拉取群聊消息
      );

常见问题

1. 拉历史消息时，日志中出现 "total count of request cloud message exceed max limit" 信息

SDK 目前的策略是：

当 getType 设置成拉云端历史消息，且拉取 x 条消息时，SDK 会从云端拉取 x 条消息。
SDK 会过滤无效的消息，例如消息被删除、非当前用户关心的消息等。
当云端历史消息中无效的消息过多，就会触发 SDK 多次分页拉取。为了提供系统的稳定性和健壮性，SDK 最多触发 3 次自动分页。当超过限制后，会出现 “total count of request cloud message exceed max limit” 的日志信息。

为了尽可能的减少此类限频机制对业务层的影响，您可以使用如下措施来减少无效消息的产生：

您可以使用在线消息，也就是说在发送消息时 onlineUserOnly 字段设置为 YES/true 。
如果是群聊消息，可以使用群定向消息指定消息的接收者，避免产生无效消息。

2. 拉云端历史消息时，消息 “丢失” ？

当 getType 设置成拉云端历史消息，且拉取 count 条消息时，SDK 会做如下操作：

SDK 先从本地拉取 count 条消息。
SDK 再次云端拉取 count 条消息，过滤掉被删除等无效的消息，如果不够 count 条，SDK 内部触发分页拉取。
将本地和云端消息进行合并，更新消息状态等信息。
从合并的消息列表中，返回 count 条消息。

一般出现消息 “丢失” 时，指的是在第 2 步中拉取的无效消息过多，导致触发了问题 1 中的限频机制，从而导致实际拉取的云端消息不够。建议按照问题 1 中的解决方法来处理，如果仍然无法解决，欢迎加入 QQ 群（468195767）反馈。

3. 拉取的历史消息，群名片等群成员信息没有实时更新？

SDK 会在消息产生时，更新当前的群名片、role 等群成员信息并存储在本地数据库中。
当拉取群历史消息时，会直接返回消息产生时的群成员信息，不会实时更新。

如果您需要获取最新的群成员信息，您可以使用 getGroupMembersInfo。

4. 拉取历史消息时卡顿

SDK 内部已对消息拉取做了性能优化，您如果碰到消息卡顿的情况，可以先尝试减少拉取的消息数 count ，如果还是不能解决问题，欢迎加入 QQ 群（788910197）反馈。

交流与反馈

欢迎加入 QQ 群进行技术交流和反馈问题，QQ 群：788910197。

历史消息