tencent cloud

文档反馈

最后更新时间:2024-01-31 15:58:31

    功能描述

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

    分页拉取

    拉取单聊历史消息拉取群聊历史消息 以及 高级接口 均可以按照相同的方式实现分页,即使用 lastMsgcount 来实现。
    通过 lastMsgcount 来实现分页。第一次拉取时 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: 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 目前的策略是:
    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
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持