Flutter

会话消息回复(Thread)

更新时间: 2024/03/07 11:46:23

NIM SDK 提供会话消息回复(Thread)功能,可引用接收到的某一条消息进行针对性的回复,形成起始于该消息的消息回复树状结构。通过该功能,用户可针对某一条消息进行提问、反馈或补充相关背景信息,且不会对频道内的会话流造成干扰。

圈组的会话消息回复功能只能在圈组内使用,且相关接口和即时通讯 IM 的不一样。

功能介绍

什么是 Thread

Thread 指以一条消息作为根消息的消息回复树状结构,示例见下图。

上图中:

  • 消息 A 是消息 B 的父消息,消息 B1 是消息 C 的父消息
  • 消息 C 是消息 B1 的子消息
  • 消息 A 是消息 B 和消息 C 的根消息
  • 消息 A、B、C 统称为 Threaded Message(串联起来的消息)
  • 一条 Threaded Message 必须有一条父消息或至少一条子消息。如果一条消息既没有父消息,也没有子消息,则为普通消息。
  • 若未开通会话消息回复功能,回复时系统会自动将所发消息转换为一条普通消息。

UI 示例

会话消息回复(Thread)的 UI 示例如下:

Thread聊天.png

前提条件

开始会话消息回复相关功能集成前,请确保:

  • 开通圈组的消息回复功能。圈组的会话消息回复功能需要在开通圈组功能的基础上额外开通后才能使用。
  • 已完成圈组初始化。

实现方法

实现会话消息回复

API调用时序

以下时序图可能因为网络问题而显示异常。如显示异常,一般刷新当前页面即可正常显示。

uml diagram

具体流程

本节仅对上图中标为橙色的流程进行说明,其他流程请参考相关文档。例如:

  • 服务器成员相关说明,可参见圈组服务器成员管理
  • 用户是否能访问某频道的相关说明,可参见频道管理中对于频道黑白名单的说明。
  • 权限相关配置说明,可参见身份组相关文档。
  1. 发送方和接收方在登录圈组前,注册onReceiveMessage消息接收事件流,监听消息接收。

    示例代码如下:

    dartNimCore.instance.qChatObserver.onReceiveMessage.listen((event) {
      //收到消息qChatMessages
      for (var qChatMessage in event) {
        //处理消息
      }
    });
    
  2. 接收方在收到消息后,调用replyMessage方法发送回复消息。

    • 需要拥有发送消息的权限才能回复消息。
    • 两条消息的serverIdchannelId 必须相同,因为只能在同一个服务器和频道内回复消息。

    示例代码如下:

    dart
    final replyMessage = getMessage();   
    final message = QChatSendMessageParam(      
      channelId: channelId,      
      serverId: serverId,      
      type: NIMMessageType.text,      
      body: "回复消息测试");
    final param = QChatReplyMessageParam(replyMessage: replyMessage, message: message);    
    NimCore.instance.qChatMessageService.replyMessage(param).then((value) {    
      if (value.isSuccess) {    
        // 回复消息成功,返回发送成功的消息具体信息   
        var message = value.data?.sentMessage;
      } else {
        // 回复消息失败
      }
    });
    
  3. onReceiveMessage事件流回调触发,发送方收到接收方回复的消息。

相关查询

根据消息 ID 批量查询回复消息

调用getMessageHistoryByIds,可根据回复消息的msgIdServer查询历史回复消息。查询结果不分页,一次最多查询 100 条。 调用时需需要传入需要查询的serverIdchannelId和回复消息列表QChatMessageRefer。该方法的回参结构QChatGetMessageHistoryResult中返回查询到的消息列表。

示例代码

dartfinal messageReferList = getMessageRefersList();
final param = QChatGetMessageHistoryByIdsParam(
  serverId: serverId,
  channelId: channelId,
  messageReferList: messageReferList);
NimCore.instance.qChatMessageService.getMessageHistoryByIds(param).then((value) {
  if (value.isSuccess) {
    // 查询成功,返回查询到的消息列表
    var messages = value.data?.messages;
  } else {
    // 查询失败
  }
});

查询某消息的父消息以及根消息

调用getReferMessages查询 Thread 中某条消息的父消息和根消息。

  • 该方法入参结构QChatGetReferMessagesParam中需要传入的消息引用类型QChatMessageReferType三种选择:

    • replay:只查询父消息
    • thread:只查询根消息
    • all:同时查询父消息消息和根消息

    QChatGetReferMessagesParam传入的需要查询的消息不能是根消息,否则会返回 414 错误码。

  • 该方法回参结构QChatGetReferMessagesResult中返回父消息和根消息。

    • 如果QChatMessageReferTypereplayall才返回父消息,否则getReplyMessage返回为 null
    • 如果QChatMessageReferTypethreadall才返回根消息,否则getThreadMessage返回为 null
  • 示例代码

    dartfinal message = getQueryMessage();
    final param = QChatGetReferMessagesParam(message: message, referType: QChatMessageReferType.replay);    
    NimCore.instance.qChatMessageService.getReferMessages(param).then((value) {
      if (value.isSuccess) {
        //查询成功
        // 如果QChatMessageReferType为replay或all才有,否则为null
        var replyMessage = value.data?.replyMessage;
        //如果QChatMessageReferType为thread或all才有,否则为null
        var threadMessage = value.data?.threadMessage;
      } else {
        // 查询失败
      }
    });
    

查询 Thread 的消息列表

调用getThreadMessages方法,可根据某个 Thread 中的任意一条消息分页查询该 Thread 的消息列表(即该 Thread 的聊天历史)。

  • 该方法的入参结构QChatGetThreadMessagesParam需要传入待查询的消息和消息查询选项QChatMessageQueryOption;回参结构QChatGetThreadMessagesResult会返回根消息、Thread 聊天信息 QChatMessageThreadInfo 和查询到的消息列表。其中QChatMessageThreadInfo中返回 Thread 的总回复数和最后一条消息的时间戳。

    QChatMessageQueryOption的参数说明如下:

    类型 参数 说明
    fromTime int 起始时间
    toTime int 结束时间,如果设置为 0 则为当前时间
    excludeMessageId int 排除消息ID。如果fromTime上有多条消息,可以通过该参数指定实际的起始时间为 excludeMsgId 对应的消息的下一条消息的时间
    limit int 查询结果条数限制,默认 100 条。如果fromTimetoTime 之间消息大于 limit 条,返回 limit 条记录;如果小于 limit 条,返回实际条数;当已经查询到头时,返回的结果列表的 size 可能会比 limit
    reverse bool 是否反向查询(默认 false ,表示从 toTime 开始往前查找历史消息),可以通过 setReverse 设置是否反向。

    如果17:00:00 到18:00:00的消息总共有200条,查询该时段最多返回 100 条:

    • 如果isReverse() ==false(即默认方式),则返回后100条,时间逆序排列,时间从新到旧
    • 如果isReverse() ==true(反向方式),则前100条,时间正序排列,时间从旧到新

    当进行首次查询时,如果要查最新的100条,则fromTime=0, toTime=0, limit=0

  • 示例代码

    dartfinal message = getQueryMessage();
    final messageQueryOption = QChatMessageQueryOption();
    final param = QChatGetThreadMessagesParam(message: message, messageQueryOption: messageQueryOption);    
    NimCore.instance.qChatMessageService.getThreadMessages(param).then((value) {
      if (value.isSuccess) {
        // 查询成功
        // 根消息
        var threadMessage = value.data?.threadMessage;
        //Thread聊天信息,包含Thread聊天的总回复数和Thread聊天中最后一条消息的时间戳
        var threadInfo = value.data?.threadInfo;
        //Thread聊天中的回复消息列表(不包含根消息)
        var messages = value.data?.messages;
      } else {
        // 查询失败
      }
    });
    

批量查询根消息meta信息

调用getMessageThreadInfos方法,可批量查询某个频道下的多个 Thread 的根消息的 meta 信息(如总回复数和最后回复时间)。

该方法的入参结构QChatGetMessageThreadInfosParam中需要传入需要查询的serverIdchannelId和根消息列表。该方法的回参结构QChatGetMessageThreadInfosResult返回 Thread 聊天信息 Map,key 为传入的根消息的 uuid,value 为 QChatMessageThreadInfo

示例代码如下:

dartfinal msgList = getThreadMsgList();
final param = QChatGetMessageThreadInfosParam(serverId: serverId, channelId: channelId, msgList: msgList);    
NimCore.instance.qChatMessageService.getMessageThreadInfos(param).then((value) {
  if (value.isSuccess) {
    // 查询成功,返回Thread聊天信息Map,key为传入根消息的uuid,value为QChatMessageThreadInfo
    var messageThreadInfoMap = value.data?.messageThreadInfoMap;
  } else {
    // 查询失败
  }
});

此文档是否对你有帮助?
有帮助
去反馈
  • 功能介绍
  • 什么是 Thread
  • UI 示例
  • 前提条件
  • 实现方法
  • 实现会话消息回复
  • API调用时序
  • 具体流程
  • 相关查询
  • 根据消息 ID 批量查询回复消息
  • 查询某消息的父消息以及根消息
  • 查询 Thread 的消息列表
  • 批量查询根消息meta信息