Extension features

Replies

A message without a reply is called a threaded message; a message with a reply is called a message reply.

A threaded message can be replied by multiple reply messages. The target of a reply message can be either a threaded message or a reply message. If the target of a reply message is a threaded message, the threaded message corresponding to the reply message is its reply object; otherwise, the thread message corresponding to the reply message is the same as the threaded message corresponding to the reply message.

All replies in the same thread consist of a thread session.

Reply

• API prototype

dart  /// Reply a message. <br>
  ///  [msg]    Message body created by {@link MessageBuilder}
  ///  [replyMsg] replied message
  ///  [resend] True: resend a message for failures. Otherwise, false. The parameter is not supported on Windows and macOS.
  ///  [Future] set a callback. The method can be called after the message is sent. For information about error code, see specific error codes.
  ///
  Future<NIMResult<void>> replyMessage(
      {required NIMMessage msg,
      required NIMMessage replyMsg,
      required bool resend});

• Parameters

Parameter	Type	Description
msg	NIMMessage	Message body created by { MessageBuilder}.
replyMsg	NIMMessage	Replied message
resend	bool	True: resend a message for failure. Otherwise, false.

• Example

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});

Note: In a superteam, uses SuperTeamService to reply a message..

Query chat threads in the cloud

• API prototype

dart  /// Query history thread chats in the cloud. The session types of P2P, advanced group, and supergroup are supported.
  ///
  ///  anchor The search anchor. The search target is the messages in a thread.
  ///  fromTime The start time of a time range
  ///  toTime The end time of a time range
  ///  limit The limit of messages returned from a query
  ///  direction The search direction
  ///  persist Whether the search result is persisted. The parameter is not supported for Windows and macOS.
  Future<NIMResult<NIMThreadTalkHistory>> queryThreadTalkHistory(
      {required NIMMessage anchor,
      required int fromTime,
      required int toTime,
      required int limit,
      required QueryDirection direction,
      required bool persist});

• Parameters

Parameter	Type	Description
anchor	NIMMessage	The search anchor. The search target is the messages in a thread.
fromTime	int	The start time
toTime	int	The end time
limit	int	The limit of messages returned from a query.
direction	QueryDirection	Query direction
persist	bool	Whether the result is persisted.

• Example

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})

Get the number of replies in a thread

Get the number of replies in a thread in the local database.

• API prototype

dart  /// Get the reply count of a thread chat. The thread message is not counted.
  ///
  /// msg  A message in a thread
  ///  Get the number of replies.
  Future<NIMResult<int>> queryReplyCountInThreadTalkBlock(NIMMessage msg);

• Parameters

Parameter	Type	Description
msg	NIMMessage	A message in a thread.

• Example

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

Quick comment

Add a quick comment to a message. The comment content is not a message, but data of long type. and the upper layer specifies the association between the comment content and the interface.

Add a quick comment

• API prototype

dart ///
 /// Add a quick comment
 ///
 /// [msg] the message to be replied
 /// [replyType] Reply type
 /// [ext] Extension field that can hold up to 8 characters.
 /// [needPush] Whether the push service is required.
 /// [needBadge] Whether the badge count is required
 /// [pushTitle] Title of a push notification
 /// [pushContent] The content of a push notification
 /// [pushPayload] Data sent in the push service in JSON
Future<NIMResult<int>> addQuickComment(NIMMessage msg, int replyType, String ext, bool needPush, bool needBadge, String pushTitle, String pushContent, Map<String, Object> pushPayload);

• Parameters

Parameter	Type	Description
msg	NIMMessage	Message to be replied
replyType	int	Type of a reply message
ext	String	Extension field that can hold up to 8 characters
needPush	bool	Whether the push service is required.
needBadge	bool	Whether the badge is required.
pushTitle	String	Title of a push notification notification
pushContent	String	The body of a push notification
pushPayload	Map<String, Object>	Custom push payload in JSON format

• Example

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

Delete a quick comment

• API prototype

dart ///
 /// Delete a quick comment
 ///
 /// [msg] the message to be replied
 /// [replyType] Reply type
 /// [ext] Extension field that can hold up to 8 characters.
 /// [needPush] Whether the push service is required.
 /// [needBadge] Whether the badge count is required
 /// [pushTitle] Title of a push notification
 /// [pushContent] The content of a push notification
 /// [pushPayload] Data sent in the push service in JSON
 Future<NIMResult<int>> removeQuickComment(NIMMessage msg, int replyType, String ext, bool needPush, bool needBadge, String pushTitle, String pushContent, Map<String, Object> pushPayload);

• Parameters

Parameter	Type	Description
msg	NIMMessage	Message to be replied
replyType	int	Type of a reply message
ext	String	Extension field that can hold up to 8 characters
needPush	bool	Whether the push service is required.
needBadge	bool	Whether the badge is required.
pushTitle	String	Title of a push notification notification
pushContent	String	The body of a push notification
pushPayload	Map<String, Object>	Custom push payload in JSON format

• Example

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

Get a quick comment

• API prototype

dart ///
 /// Get the list of quick comments
 ///
 ///[ msgList] A list of messages for quick comments. Up to 20 messages are allowed.
 ///
Future<NIMResult<List<NIMQuickCommentOptionWrapper>>> queryQuickComment(List<NIMMessage> msgList)

• Parameters

Parameter	Type	Description
msgList	List	A list of messages for quick comments. Up to 20 messages are allowed.

• Example

dartawait NimCore.instance.messageService.queryQuickComment(msglist)

Listen for new comments

• API prototype

dart ///
 /// Listen for new comments
 ///
 /// The method contains two parameters, The key parameter of `NIMHandleQuickCommentOption` is used to fetch the full message on the server. The commentOption parameter contains the comment for the message.
 ///
  final StreamController<NIMHandleQuickCommentOption> onQuickCommentAdd =
  StreamController<NIMHandleQuickCommentOption>.broadcast();

NIMHandleQuickCommentOption representation:

Parameter	Type	Description
key	NIMMessageKey	The key of a message. The key can be used to fetch the full message on the server.
commentOption	NIMQuickCommentOption	The data of a quick comment.

• Example

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

  });

Listen for deleting quick comment

• API prototype

dart ///
 /// Listen for new comments
 ///
 /// The method contains two parameters, The key parameter of `NIMHandleQuickCommentOption` is used to fetch the full message on the server. The commentOption parameter contains the comment for the message.
 ///
   final StreamController<NIMHandleQuickCommentOption> onQuickCommentRemove =
  StreamController<NIMHandleQuickCommentOption>.broadcast();

NIMHandleQuickCommentOption representation:

Parameter	Type	Description
key	NIMMessageKey	The key of a message. The key can be used to fetch the full message on the server.
commentOption	NIMQuickCommentOption	The data of a quick comment.

• Example

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

  });

Bookmarks

You can add a string within 20,000 characters long as a bookmark

Add a bookmark

• API prototype

dart  /// Add a bookmark message
  ///
  /// [type] Bookmark type
  /// [data] data of a bookmark message. Up to 20 KB is allowed.
  /// [ext] extension field that can hold 1KB data.
  /// [uniqueId] unique message ID
 Future<NIMResult<NIMCollectInfo>> addCollect({
    required int type,
    required String data,
    String? ext,
    String? uniqueId,
  }) ;

• Parameters

Parameter	Type	Description
type	int	Bookmark type
data	String	Data of a bookmark message. Up to 20KB is allowed.
ext	String	Extension field that contains up to 1KB data
uniqueId	String	Unique message ID

• Example

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

Remove multiple bookmark messages at a time

• API prototype

dart  /// Remove multiple bookmark messages at a time.
  ///
  /// [collects] collection of bookmark messages to be removed
  /// [id] and [createTime] in [NIMCollectInfo] are required
  ///
 Future<NIMResult<int>> removeCollect(List<NIMCollectInfo> collects);

• Parameters

Parameter	Type	Description
collects	List	List of information about bookmarks to be removed. Each pair consists of a bookmark ID and the creation time

• Example

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

Update the extension field of the bookmark

• API prototype

dart ///
 /// Update the extension field of a bookmark message
 /// [info] a bookmark to be updated
 /// If [info.ext] is unspecified, the ext field is deleted.
 ///
 Future<NIMResult<NIMCollectInfo>> updateCollect(NIMCollectInfo info);

• Parameters

Parameter	Type	Description
info	NIMCollectInfo	a bookmark to be updated

• Example

dartNIMCollectInfo info = ...; // get a bookmark
collectInfo.ext = 'update collect ext';  // Edit the extension field.
await NimCore.instance.messageService.updateCollect(collectInfo);

Query paginated bookmarks

• API prototype

dart  ///
  /// Query bookmark messages on the server by pagination
  ///
  /// [anchor] last bookmark message in the query excluded in the query result.
  /// [type] Query type. If unspecified, all types of messages are returned.
  /// [toTime] end time of a time range in milliseconds
  /// [limit] limit of messages returned from a query. A maximum of 100 messages are allowed.
  /// [direction] query direction
  ///
  Future<NIMResult<List<NIMCollectInfo>>> queryCollect({
    NIMCollectInfo? anchor,
    int toTime = 0,
    int? type,
    int limit = 100,
    QueryDirection direction = QueryDirection.QUERY_OLD,
  });

• Parameters

Parameter	Type	Description
anchor	NIMCollectInfo	The last bookmark message in the query excluded in the query result.
toTime	int	The end time of a time range in milliseconds
limit	int	limit of messages returned from a query. A maximum of 100 messages are allowed.
direction	QueryDirection	Query direction

• Example

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

PIN tag

All users in the session can add a PIN tag to a message, remove the PIN tag from a message, query PIN messages, and update the extension field. A message can only have one PIN tag. When multiple users add a PIN tag to the same message, the later PIN tag will overwrite the earlier PIN tag.

Add a PIN tag to a message

• API prototype

dart  ///
  /// Add a PIN message
  ///
  /// [message] pinned message
  /// [ext] extension field
  ///
  Future<NIMResult<void>> addMessagePin(NIMMessage message, String? ext) ;

• Parameters

Parameter	Type	Description
message	NIMMessage	The message with a PIN tag
ext	String	Extension field

• Example

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

Update a PIN message

• API prototype

dart  ///
  /// Update a PIN message
  ///
  /// [message] pinned message
  /// [ext] extension field
  ///
  Future<NIMResult<void>> updateMessagePin(NIMMessage message, String? ext);

• Parameters

Parameter	Type	Description
message	NIMMessage	The message with a PIN tag
ext	String	Extension field

• Example

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

Remove the PIN tag of a message

• API prototype

dart  ///
  /// Delete a PIN message
  ///
  /// [message] pinned message
  /// [ext] extension field
  ///
  Future<NIMResult<void>> removeMessagePin(NIMMessage message, String? ext);

• Parameters

Parameter	Type	Description
message	NIMMessage	The message with a PIN tag
ext	String	Extension field

• Example

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

Get a list of PIN messages

• API prototype

dart  /// Query all of PIN messages in a session
  ///
  /// [sessionId] session ID
  /// [sessionType] session type
  ///
  Future<NIMResult<List<NIMMessagePin>>> queryMessagePinForSession( String sessionId, NIMSessionType sessionType);

• Parameters

Parameter	Type	Description
sessionId	String	The ID of a session.
sessionType	NIMSessionType	The type of a session.

• Example

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

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

Listen for events of PIN messages

Events of PIN messages include adding a PIN tag, updating a PIN tag, and deleting the PIN tag. The base class of events is NIMMessagePinEvent, and the derived classes include adding a PIN tag NIMMessagePinAddedEvent, updating a PIN tag NIMMessagePinUpdatedEvent, and deleting a PIN tag NIMMessagePinRemovedEvent.

• API prototype

dartclass MessageService {
  /// Notifications for events of PIN messages
  Stream<NIMMessagePinEvent> get onMessagePinNotify;
}

• NIMMessagePinEvent representation

Parameter	Type	Description
pin	NIMMessagePin	PIN message

• Example

dartawait NimCore.instance.messageService.onMessagePinNotify.listen(
    (messagePinEvent) {
        if (messagePinEvent is NIMMessagePinAddedEvent) {
            /// Add a PIN tag to a message
        } else if (messagePinEvent is NIMMessagePinUpdatedEvent) {
            /// Update the PIN tag of a message
        } else if (messagePinEvent is NIMMessagePinRemovedEvent) {
            /// Delete the PIN tag of a message
        }
    }
);

Pinned sessions

Add a pinned session

• API prototype

dart  ///
  /// Pin a session
  ///
  /// [sessionId]   The ID of a session.
  /// [sessionType] session type
  /// [ext] Extension field that can hold up to 512 characters
  ///
  Future<NIMResult<NIMStickTopSessionInfo>> addStickTopSession(String sessionId, NIMSessionType sessionType, String ext);

• Parameters

Parameter	Type	Description
sessionId	String	The ID of a session.
sessionType	NIMSessionType	The type of a session.
ext	String	Extension field that can hold up to 512 characters

• Example

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

Delete a pinned session

• API prototype

dart  ///
  /// Delete a pinned session
  ///
  /// [sessionId]   The ID of a session.
  /// [sessionType] session type
  /// [ext] Extension field that can contain up to 512 characters The parameter is not supported for Windows and macOS.
  ///
  Future<NIMResult<void>> removeStickTopSession(String sessionId, NIMSessionType sessionType, String ext);

• Parameters

Parameter	Type	Description
sessionId	String	The ID of a session.
sessionType	NIMSessionType	The type of a session.
ext	String	Extension field that can contain up to 512 characters. The parameter is not supported for Windows and macOS.

• Example

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

Update the extension field of a pinned session

• API prototype

dart  ///
  /// Update the extension field of a pinned session
  ///
  /// [sessionId]   The ID of a session.
  /// [sessionType] session type
  /// [ext] Extension field that can contain up to 512 characters
  ///
  Future<NIMResult<void>> updateStickTopSession(String sessionId, NIMSessionType sessionType, String ext);

• Parameters

Parameter	Type	Description
sessionId	String	The ID of a session.
sessionType	NIMSessionType	The type of a session.
ext	String	Extension field that can hold up to 512 characters

• Example

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

Get the pinned sessions

Note: You need to set the notificationStickTopSession of the initialization parameter SDKOptions to true, and enable the synchronization of the pinned session list before you can query the accurate pinned session list using the following interface. Otherwise, the queried list does not include changes during the offline period.

• API prototype

dart  ///
  /// Get the list of pinned sessions
  ///
  Future<NIMResult<List<NIMStickTopSessionInfo>>> queryStickTopSession()

• Example

dart  NimCore.instance.messageService.queryStickTopSession();

Listen to the synchronization of pinned sessions

• API prototype

dart  ///
  /// Returned data by the method of synchronizing pinned sessions for multiple devices. The parameter is the information about the pinned session. The parameter is not supported on Windows and macOS.
  ///
  final StreamController<List<NIMStickTopSessionInfo>> onSyncStickTopSession =
  StreamController<List<NIMStickTopSessionInfo>>.broadcast();

• Example

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

Listen to new pinned sessions

• API prototype

dart  ///
  /// The returned data by the method of synchronizing a new pinned session for multiple devices. The parameter is the information about the pinned session.
  ///
  final StreamController<NIMStickTopSessionInfo> onStickTopSessionAdd =
  StreamController<NIMStickTopSessionInfo>.broadcast();

• Example

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

Listen to removing pinned sessions

• API prototype

dart  ///
  /// Returned data by the method of removing a pinned session for multiple devices. The parameter is the information about the pinned session.
  ///
  final StreamController<NIMStickTopSessionInfo> onStickTopSessionRemove =
  StreamController<NIMStickTopSessionInfo>.broadcast();

• Example

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

Listen to updating pinned sessions

• API prototype

dart  ///
  /// Returned data by the method of updating a pinned session for multiple devices. The parameter is the information about the pinned session.
  ///
  final StreamController<NIMStickTopSessionInfo> onStickTopSessionUpdate =
  StreamController<NIMStickTopSessionInfo>.broadcast();

• Example

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