即时通信 IM Flutter（历史消息）

一、功能描述

·拉取历史消息的 API 在类 TencentImSDKPlugin.v2TIMManager.getMessageManager() 中。

·除了支持单聊、群聊历史消息的拉取外，还提供了高级接口以支持按指定方向拉取、按指定起点和指定时间范围拉取。

·除了支持单独拉取本地历史消息外，还支持拉取云端历史消息。

注意：说明：

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

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

·体验版：免费存储 7 天，不支持延长。

·专业版：免费存储 7 天，支持延长。

·旗舰版：免费存储 30 天，支持延长。

·企业版：免费存储 90 天，支持延长。

注意：说明：

二、拉取单聊历史消息

你可以调用接口 getC2CHistoryMessageList （点击查看详情）获取单聊历史消息。

在网络正常的情况下会拉取最新的云端数据。如果网络出现异常，SDK 会返回本地存储的历史消息。

如果你仅仅想拉取本地历史消息，详细可参见 高级接口 。

本接口支持分页拉取，详细可参见：分页拉取。

示例代码如下：

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

三、拉取群聊历史消息

你可以调用接口 getGroupHistoryMessageList （点击查看详情）获取群聊历史消息。

在网络正常的情况下会拉取最新的云端数据。如果网络出现异常，SDK 会返回本地存储的历史消息。

如果你仅仅想拉取本地历史消息，详细可参见 高级接口 。

本接口支持分页拉取，详细可参见：分页拉取。

示例代码如下：

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

四、高级接口

如果以上的普通接口无法满足你对拉取历史消息的需求，我们还提供了高级接口 getHistoryMessageList （点击查看详情）。

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

·支持设置拉取消息的位置：从本地拉取、从云端拉取。

·支持按照指定的方向拉取：往消息时间更老的方向拉取、往消息时间更新的方向拉取。

·支持拉取本地指定的消息类型：文本、图片、语音、视频、文件、表情、群 tips 消息、合并消息、自定义消息等。

接口原型：

// 拉取单聊历史消息 // 首次拉取，lastMsgID 设置为 null // 再次拉取时，lastMsgID 可以使用返回的消息列表中的最后一条消息的id V2TimValueCallback<List<V2TimMessage>> getHistoryMessageListRes = await TencentImSDKPlugin.v2TIMManager .getMessageManager() .getHistoryMessageList( getType: HistoryMsgGetTypeEnum.V2TIM_GET_LOCAL_OLDER_MSG, // 拉取消息的位置及方向 userID: "userID", // 用户id 拉取单聊消息，需要指定对方的 userID，此时 groupID 传空即可。 groupID: "groupID", // 群组id 拉取群聊消息，需要指定群聊的 groupID，此时 userID 传空即可。 count: 10, // 拉取数据数量 lastMsgID: null, // 拉取起始消息id // 仅能在群聊中使用该字段。 // 设置 lastMsgSeq 作为拉取的起点，返回的消息列表中包含这条消息。 // 如果同时指定了 lastMsg 和 lastMsgSeq，SDK 优先使用 lastMsg。 // 如果均未指定 lastMsg 和 lastMsgSeq，拉取的起点取决于是否设置 getTimeBegin。设置了，则使用设置的范围作为起点；未设置，则使用最新消息作为起点。 lastMsgSeq: -1, messageTypeList: [], // 用于过滤历史信息属性，若为空则拉取所有属性信息。 ); if (getHistoryMessageListRes.code == 0) { //获取成功 }

参数说明：

五、分页拉取

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

·通过 lastMsg 和 count 来实现分页。第一次拉取时 lastMsg 可以设置为空，使用消息列表中返回来最后一条消息作为下一次拉取的 lastMsg 从而拉取下一页数据。

·当 lastMsg 设置为空时，SDK 会默认从最新的消息开始返回。

·当设置 lastMsg 后，返回的消息列表不包含设置的 lastMsg。

·返回的消息列表中，越新的消息越靠前。

注意：说明：

注意：1. 为了不影响历史消息拉取速度，建议分页时 count 设置为 20。

注意：2. 由于返回的消息列表会包含 lastMsgSeq 所对应的消息，所以在拉取群聊历史消息时，不建议使用 lastMsgSeq 来续拉。

六、仅拉取本地消息

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

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

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

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

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

七、跳转到群 @ 消息后拉取

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

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

// 获取群 @ 消息对应的的 sequenceint 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 目前的策略是：

1. 当 getType 设置成拉云端历史消息，且拉取 x 条消息时，SDK 会从云端拉取 x 条消息。

2. SDK 会过滤无效的消息，例如消息被删除、非当前用户关心的消息等。

3. 当云端历史消息中无效的消息过多，就会触发 SDK 多次分页拉取。
为了提供系统的稳定性和健壮性，SDK 最多触发 3 次自动分页。当超过限制后，会出现 “total count of request cloud message exceed max limit” 的日志信息。

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

·你可以使用在线消息，也就是说在发送消息时 onlineUserOnly 字段设置为 YES/true 。

·如果是群聊消息，可以使用群定向消息指定消息的接收者，避免产生无效消息。

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

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

1. SDK 先从本地拉取 count 条消息。

2. SDK 再次云端拉取 count 条消息，过滤掉被删除等无效的消息，如果不够 count 条，SDK 内部触发分页拉取。

3. 将本地和云端消息进行合并，更新消息状态等信息。

4. 从合并的消息列表中，返回 count 条消息。

一般出现消息 “丢失” 时，指的是在第 2 步中拉取的无效消息过多，导致触发了 问题 1 中的限频机制 ，从而导致实际拉取的云端消息不够。
建议按照 问题 1 中的解决方法 来处理，如果仍然无法解决，联系我们 交流。

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

·SDK 会在消息产生时，更新当前的群名片、role 等群成员信息并存储在本地数据库中。

·当拉取群历史消息时，会直接返回消息产生时的群成员信息，不会实时更新。

如果你需要获取最新的群成员信息，你可以使用 getGroupMembersInfo(点击查看详情)。

十一、4. 拉取历史消息时卡顿

SDK 内部已对消息拉取做了性能优化，你如果碰到消息卡顿的情况，可以先尝试减少拉取的消息数 count 。