聊天扩展

消息回复（thread）

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

上图中：

• 消息 A 是消息 B 的父消息，消息 B1 是消息 C 的父消息
• 消息 C 是消息 B1 的子消息
• 消息 A 是消息 B 和消息 C 的根消息
• 消息 A、B、C 统称为 Threaded Message（串联起来的消息）

一条 Threaded Message 必须有一条父消息或至少一条子消息。如果一条消息既没有父消息，也没有子消息，则为普通消息。

• 消息回复能力需要单独在云信控制台开通。在控制台应用管理 > 产品功能 > IM 即时通讯 > 全局功能开通会话消息回复。

• 若未开通回复功能，回复时系统会自动将所发消息转换为一条普通消息。

消息回复

• API 原型

dart  ///回复消息。<br>
  ///  [msg]    带发送的消息体，由{@link MessageBuilder}构造
  ///  [replyMsg] 被回复的消息
  ///  [resend] 如果是发送失败后重发，标记为true，否则填false（Windows和macOS暂不支持）
  ///  [Future] 可以设置回调函数。消息发送完成后才会调用，如果出错，会有具体的错误代码。
  ///
  Future<NIMResult<void>> replyMessage(
      {required NIMMessage msg,
      required NIMMessage replyMsg,
      required bool resend});

• 参数说明

参数	类型	说明
msg	NIMMessage	带发送的消息体，由{ MessageBuilder}构造
replyMsg	NIMMessage	被回复的消息
resend	bool	如果是发送失败后重发，标记为 true，否则填 false

• 示例

dartNIMResult<NIMMessage> retCreateMsg =
        await MessageBuilder.createTextMessage(
            sessionId: inputParams['toAccount'] as String,
            sessionType: NIMSessionType.p2p,
            text: inputParams['text'] as String);
        var message = retCreateMsg.data;
  await NimCore.instance.messageService.replyMessage(
      {msg: message,
      message:message,
      resend:true});

注意：在超大群中，回复消息应使用 SuperTeamService。

查询 thread 聊天云端历史

• API 原型

dart  ///  查询thread聊天云端历史（支持p2p、群、超大群）
  ///
  ///  anchor 查找锚点，查找对象为此消息所在的thread中的消息
  ///  fromTime 起始时间
  ///  toTime 终止时间
  ///  limit 条数限制
  ///  direction 方向
  ///  persist 是否持久化（Windows和macOS暂不支持）
  Future<NIMResult<NIMThreadTalkHistory>> queryThreadTalkHistory(
      {required NIMMessage anchor,
      required int fromTime,
      required int toTime,
      required int limit,
      required QueryDirection direction,
      required bool persist});

• 参数说明

参数	类型	说明
anchor	NIMMessage	查找锚点，查找对象为此消息所在的 thread 中的消息
fromTime	int	起始时间
toTime	int	终止时间
limit	int	条数限制
direction	QueryDirection	方向
persist	bool	是否持久化

• 示例

dart  NIMResult<NIMMessage> retCreateMsg =
        await MessageBuilder.createTextMessage(
            sessionId: inputParams['toAccount'] as String,
            sessionType: NIMSessionType.p2p,
            text: inputParams['text'] as String);
        var message = retCreateMsg.data;
   await NimCore.instance.messageService.queryThreadTalkHistory(
      {anchor:message,
      fromTime:fromTime,
      toTime:toTime,
      limit:limit,
      directio:direction,
      persist:persist})

获取 thread 消息回复数

本地获取某 thread 消息的回复消息的条数。

• API 原型

dart  /// 本地获取某thread消息的回复消息的条数，thread消息不被计入总数
  ///
  ///  msg thread中的某一条消息
  ///  回复消息数
  Future<NIMResult<int>> queryReplyCountInThreadTalkBlock(NIMMessage msg);

Web 不支持该接口。

• 参数说明

参数	类型	说明
msg	NIMMessage	thread 中的某一条消息

• 示例

dartint count =  await NimCore.instance.messageService.queryReplyCountInThreadTalkBlock(msg:message);

快捷评论

可以对消息进行快捷评论。评论内容并非一条消息，而是一个 long 类型，由上层指定评论内容与界面展示之间的联系

增加评论

• API 原型

dart ///
 /// 增加一条快捷评论
 ///
 /// [msg] 回复对象
 /// [replyType] 回复类型
 /// [ext] 自定义扩展字段，最大8字符
 /// [needPush] 是否需要推送
 /// [needBadge] 是否需要角标
 /// [pushTitle] 推送标题
 /// [pushContent] 推送内容
 /// [pushPayload] 第三方自定义的推送属性，限制json类型
Future<NIMResult<int>> addQuickComment(NIMMessage msg, int replyType, String ext, bool needPush, bool needBadge, String pushTitle, String pushContent, Map<String, Object> pushPayload);

• 参数说明

参数	类型	说明
msg	NIMMessage	回复对象
replyType	int	回复类型
ext	String	自定义扩展字段，最大 8 字符
needPush	bool	是否需要推送
needBadge	bool	是否需要角标
pushTitle	String	推送标题
pushContent	String	推送内容
pushPayload	Map<String, Object>	第三方自定义的推送属性，限制 json 类型

• 示例

dartawait NimCore.instance.messageService.addQuickComment(message, replytype, msgExt, needpush, needbadge,pushTitle, pushContent, pushPayload);

删除评论

• API 原型

dart ///
 /// 删除一条快捷评论
 ///
 /// [msg] 回复对象
 /// [replyType] 回复类型
 /// [ext] 自定义扩展字段，最大8字符
 /// [needPush] 是否需要推送
 /// [needBadge] 是否需要角标
 /// [pushTitle] 推送标题
 /// [pushContent] 推送内容
 /// [pushPayload] 第三方自定义的推送属性，限制json类型
 Future<NIMResult<int>> removeQuickComment(NIMMessage msg, int replyType, String ext, bool needPush, bool needBadge, String pushTitle, String pushContent, Map<String, Object> pushPayload);

• 参数说明

参数	类型	说明
msg	NIMMessage	回复对象
replyType	int	回复类型
ext	String	自定义扩展字段，最大 8 字符
needPush	bool	是否需要推送
needBadge	bool	是否需要角标
pushTitle	String	推送标题
pushContent	String	推送内容
pushPayload	Map<String, Object>	第三方自定义的推送属性，限制 json 类型

• 示例

dartawait NimCore.instance.messageService.removeQuickComment(message, replytype, msgExt, needpush, needbadge,pushTitle, pushContent, pushPayload);

获取评论

• API 原型

dart ///
 /// 获取快捷评论列表
 ///
 /// [msgList] 每个元素是被查询快捷评论的消息，数量不超过20
 ///
Future<NIMResult<List<NIMQuickCommentOptionWrapper>>> queryQuickComment(List<NIMMessage> msgList)

• 参数说明

参数	类型	说明
msgList	List	每个元素是被查询快捷评论的消息，数量不超过 20

• 示例

dartawait NimCore.instance.messageService.queryQuickComment(msglist)

监听新增评论

• API 原型

dart ///
 /// 监听新增评论
 ///
 /// 参数有两部分构成，一部分可以确定被评论的消息；另一部分是评论信息
 ///
  final StreamController<NIMHandleQuickCommentOption> onQuickCommentAdd =
  StreamController<NIMHandleQuickCommentOption>.broadcast();

NIMHandleQuickCommentOption 类型说明：

参数	类型	说明
key	NIMMessageKey	消息的关键信息，通过这些信息可以从服务端查询到该消息的完整部分
commentOption	NIMQuickCommentOption	快速评论的信息

• 示例

dart   NimCore.instance.messageService.onQuickCommentAdd.listen(( NIMHandleQuickCommentOption event) {

  });

监听移除评论

• API 原型

dart ///
 /// 监听新增评论
 ///
 /// 参数有两部分构成，一部分可以确定被评论的消息；另一部分是评论信息
 ///
   final StreamController<NIMHandleQuickCommentOption> onQuickCommentRemove =
  StreamController<NIMHandleQuickCommentOption>.broadcast();

NIMHandleQuickCommentOption 类型说明：

参数	类型	说明
key	NIMMessageKey	消息的关键信息，通过这些信息可以从服务端查询到该消息的完整部分
commentOption	NIMQuickCommentOption	快速评论的信息

• 示例

dart   NimCore.instance.messageService.onQuickCommentRemove.listen(( NIMHandleQuickCommentOption event) {

  });

收藏夹

允许用户添加一个 20k 以内的字符串作为收藏

添加一条收藏

• API 原型

dart  /// 添加一条收藏
  ///
  /// [type] 收藏类型
  /// [date] 收藏内容，最大20k
  /// [ext] 扩展字段，最大1k
  /// [uniqueId] 去重唯一ID
 Future<NIMResult<NIMCollectInfo>> addCollect({
    required int type,
    required String data,
    String? ext,
    String? uniqueId,
  }) ;

• 参数说明

参数	类型	说明
type	int	收藏类型
data	String	收藏内容，最大 20k
ext	String	扩展字段，最大 1k
uniqueId	String	去重唯一 ID

• 示例

javaawait NimCore.instance.messageService.addCollect(type, data, ext, uniqueId);

批量移除收藏

• API 原型

dart  /// 批量移除收藏
  ///
  /// [collects] 要移除的收藏的请求
  /// [NIMCollectInfo] 中 [id] 和 [createTime] 为必填字段
  ///
 Future<NIMResult<int>> removeCollect(List<NIMCollectInfo> collects);

• 参数说明

参数	类型	说明
collects	List	要移除的收藏的关键信息组成的列表，每一项为一个 Pair，其中第一项为收藏的 ID，第二项为收藏的创建时间

• 示例

dartawait NimCore.instance.messageService.removeCollect(collects);

更新收藏的扩展字段

• API 原型

dart ///
 /// 更新一个收藏的扩展字段
 /// [info] 要更新的收藏对象
 /// 如果 [info.ext] 为空，表示删除ext字段
 ///
 Future<NIMResult<NIMCollectInfo>> updateCollect(NIMCollectInfo info);

• 参数说明

参数	类型	说明
info	NIMCollectInfo	要更新的收藏对象

• 示例

dartNIMCollectInfo info = ...; // 获取收藏对象
collectInfo.ext = 'update collect ext';  // 修改 ext 字段
await NimCore.instance.messageService.updateCollect(collectInfo);

分页查询收藏列表

• API 原型

dart  ///
  /// 从服务端分页查询收藏列表
  ///
  /// [anchor] 结束查询的最后一条收藏(不包含在查询结果中)
  /// [type] 查询类型，如果为空则返回所有类型
  /// [toTime] 结束时间点单位毫秒
  /// [limit] 本次查询的消息条数上限(最多100条)
  /// [direction] 查询方向
  ///
  Future<NIMResult<List<NIMCollectInfo>>> queryCollect({
    NIMCollectInfo? anchor,
    int toTime = 0,
    int? type,
    int limit = 100,
    QueryDirection direction = QueryDirection.QUERY_OLD,
  });

• 参数说明

参数	类型	说明
anchor	NIMCollectInfo	结束查询的最后一条收藏(不包含在查询结果中)
toTime	int	结束时间点单位毫秒
limit	int	本次查询的消息条数上限(最多 100 条)
direction	QueryDirection	查询方向

• 示例

dartawait NimCore.instance.messageService.queryCollect(anchor,toTime,limit,direction);

PIN 标记

一条消息可以被所在会话的所有用户 PIN，取消 PIN 和查询 PIN，以及更新扩展字段。一条消息只能有一个 PIN，多个用户 PIN 同一条消息时，较晚的 PIN 会覆盖较早的 PIN

PIN 一条消息

• API 原型

dart  ///
  /// PIN一条消息
  ///
  /// [message] 被PIN的消息
  /// [ext] 扩展字段
  ///
  Future<NIMResult<void>> addMessagePin(NIMMessage message, String? ext) ;

• 参数说明

参数	类型	说明
message	NIMMessage	被 PIN 的消息
ext	String	扩展字段

• 示例

dartawait NimCore.instance.messageService.addMessagePin(message, ext);

更新一条消息的 PIN

• API 原型

dart  ///
  /// 更新一条消息的PIN
  ///
  /// [message] 被PIN的消息
  /// [ext] 扩展字段
  ///
  Future<NIMResult<void>> updateMessagePin(NIMMessage message, String? ext);

• 参数说明

参数	类型	说明
message	NIMMessage	被 PIN 的消息
ext	String	扩展字段

• 示例

dartawait NimCore.instance.messageService.updateMessagePin(message, ext);

移除一条消息的 PIN

• API 原型

dart  ///
  /// 删除一条消息的PIN
  ///
  /// [message] 被PIN的消息
  /// [ext] 扩展字段
  ///
  Future<NIMResult<void>> removeMessagePin(NIMMessage message, String? ext);

• 参数说明

参数	类型	说明
message	NIMMessage	被 PIN 的消息
ext	String	扩展字段

• 示例

dartawait NimCore.instance.messageService.removeMessagePin(message, ext);

获取 PIN 消息列表

• API 原型

dart  /// 查询会话所有的 PIN
  ///
  /// [sessionId] 会话ID
  /// [sessionType] 会话类型
  ///
  Future<NIMResult<List<NIMMessagePin>>> queryMessagePinForSession( String sessionId, NIMSessionType sessionType);

• 参数说明

参数	类型	说明
sessionId	String	会话 ID
sessionType	NIMSessionType	会话类型

• 示例

dartawait NimCore.instance.messageService.queryMessagePinForSession(sessionId, sessionType);

1caa590e5-28e2-4b79-b6fd-a64ff09c5bec 1caa590e5-28e2-4b79-b6fd-a64ff09c5bec

消息 PIN 事件监听

消息 PIN 事件包括添加事件、更新事件、删除事件；事件封装基类为 NIMMessagePinEvent，派生类包括添加事件 NIMMessagePinAddedEvent、更新事件 NIMMessagePinUpdatedEvent、删除事件 NIMMessagePinRemovedEvent。

• API 原型

dartclass MessageService {
  /// 消息PIN事件通知
  Stream<NIMMessagePinEvent> get onMessagePinNotify;
}

• NIMMessagePinEvent 参数说明

参数	类型	说明
pin	NIMMessagePin	消息 PIN 对象

• 示例

dartawait NimCore.instance.messageService.onMessagePinNotify.listen(
    (messagePinEvent) {
        if (messagePinEvent is NIMMessagePinAddedEvent) {
            /// 消息 PIN 添加事件
        } else if (messagePinEvent is NIMMessagePinUpdatedEvent) {
            /// 消息 PIN 更新事件
        } else if (messagePinEvent is NIMMessagePinRemovedEvent) {
            /// 消息 PIN 删除事件
        }
    }
);

会话置顶

云信提供会话置顶功能，支持多端同步，并且支持最多 100 个会话置顶。

添加一个置顶会话

• API 原型

dart  ///
  /// 添加一个置顶会话
  ///
  /// [sessionId]   会话ID
  /// [sessionType] 会话类型
  /// [ext] 扩展字段，最大512字符
  ///
  Future<NIMResult<NIMStickTopSessionInfo>> addStickTopSession(String sessionId, NIMSessionType sessionType, String ext);

• 参数说明

参数	类型	说明
sessionId	String	会话 ID
sessionType	NIMSessionType	会话类型
ext	String	扩展字段，最大 512 字符

• 示例

dartNimCore.instance.messageService.addStickTopSession(sessionId, sessionType, ext);

删除一个置顶会话

• API 原型

dart  ///
  /// 删除一个置顶会话
  ///
  /// [sessionId]   会话ID
  /// [sessionType] 会话类型
  /// [ext] 扩展字段，最大512字符（Windows 和 macOS 暂不支持）
  ///
  Future<NIMResult<void>> removeStickTopSession(String sessionId, NIMSessionType sessionType, String ext);

• 参数说明

参数	类型	说明
sessionId	String	会话 ID
sessionType	NIMSessionType	会话类型
ext	String	扩展字段，最大 512 字符（Windows 和 macOS 暂不支持）

• 示例

dartNimCore.instance.messageService.removeStickTopSession(sessionId, sessionType, ext);

更新扩展字段

• API 原型

dart  ///
  /// 更新一个会话在置顶上的扩展字段
  ///
  /// [sessionId]   会话ID
  /// [sessionType] 会话类型
  /// [ext]  扩展字段，最大512字符
  ///
  Future<NIMResult<void>> updateStickTopSession(String sessionId, NIMSessionType sessionType, String ext);

• 参数说明

参数	类型	说明
sessionId	String	会话 ID
sessionType	NIMSessionType	会话类型
ext	String	扩展字段，最大 512 字符

• 示例

dartNimCore.instance.messageService.updateStickTopSession(sessionId, sessionType, ext);

获取置顶会话列表

注意：需要先设置初始化参数 SDKOptions 的 notifyStickTopSession 为 true，开启置顶会话列表的同步，方可通过以下接口查询到准确的置顶会话列表，否则查询到的列表不包含离线期间的改动。

• API 原型

dart  ///
  /// 获取置顶会话信息的列表
  ///
  Future<NIMResult<List<NIMStickTopSessionInfo>>> queryStickTopSession()

• 示例

dart  NimCore.instance.messageService.queryStickTopSession();

监听同步置顶会话

• API 原型

dart  ///
  /// 同步置顶会话的多端同步回包，参数为会话的置顶信息（Windows 和 macOS 暂不支持）
  ///
  final StreamController<List<NIMStickTopSessionInfo>> onSyncStickTopSession =
  StreamController<List<NIMStickTopSessionInfo>>.broadcast();

Web 不支持该接口。

• 示例

dart  NimCore.instance.messageService.onSyncStickTopSession.listen((List<NIMStickTopSessionInfo> event) {
          });

监听新增置顶会话

• API 原型

dart  ///
  /// 增加一条置顶会话的多端同步回包，参数为会话的置顶信息
  ///
  final StreamController<NIMStickTopSessionInfo> onStickTopSessionAdd =
  StreamController<NIMStickTopSessionInfo>.broadcast();

Web 不支持该接口。

• 示例

dart  NimCore.instance.messageService.onStickTopSessionAdd.listen((NIMStickTopSessionInfo event) {
          });

监听移除置顶会话

• API 原型

dart  ///
  /// 移除一条置顶会话的多端同步回包，参数为会话的置顶信息
  ///
  final StreamController<NIMStickTopSessionInfo> onStickTopSessionRemove =
  StreamController<NIMStickTopSessionInfo>.broadcast();

Web 不支持该接口。

• 示例

dart  NimCore.instance.messageService.onStickTopSessionRemove.listen((NIMStickTopSessionInfo event) {
          });

监听更新置顶会话

• API 原型

dart  ///
  /// 更新一条置顶会话的扩展字段的多端同步回包，参数为会话的置顶信息
  ///
  final StreamController<NIMStickTopSessionInfo> onStickTopSessionUpdate =
  StreamController<NIMStickTopSessionInfo>.broadcast();

Web 不支持该接口。

• 示例

dart  NimCore.instance.messageService.onStickTopSessionUpdate.listen((NIMStickTopSessionInfo event) {
          });