Extension

Update time: 2023/02/01 17:16:15

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
  /// 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
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.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
  /// 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
  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
  /// 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
int 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
 ///
 /// 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
await NimCore.instance.messageService.addQuickComment(message, replytype, msgExt, needpush, needbadge,pushTitle, pushContent, pushPayload);

Delete a quick comment

  • API prototype
 ///
 /// 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
await NimCore.instance.messageService.removeQuickComment(message, replytype, msgExt, needpush, needbadge,pushTitle, pushContent, pushPayload);

Get a quick comment

  • API prototype
 ///
 /// 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
await NimCore.instance.messageService.queryQuickComment(msglist)

Listen for new comments

  • API prototype
 ///
 /// 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
   NimCore.instance.messageService.onQuickCommentAdd.listen(( NIMHandleQuickCommentOption event) {

  });

Listen for deleting quick comment

  • API prototype
 ///
 /// 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
   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
  /// 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
await NimCore.instance.messageService.addCollect(type, data, ext, uniqueId);

Remove multiple bookmark messages at a time

  • API prototype
  /// 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
await NimCore.instance.messageService.removeCollect(collects);

Update the extension field of the bookmark

  • API prototype
 ///
 /// 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
NIMCollectInfo info = ...; // get a bookmark
collectInfo.ext = 'update collect ext';  // Edit the extension field.
await NimCore.instance.messageService.updateCollect(collectInfo);

Query paginated bookmarks

  • API prototype
  ///
  /// 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
await 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
  ///
  /// 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
await NimCore.instance.messageService.addMessagePin(message, ext);

Update a PIN message

  • API prototype
  ///
  /// 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
await NimCore.instance.messageService.updateMessagePin(message, ext);

Remove the PIN tag of a message

  • API prototype
  ///
  /// 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
await NimCore.instance.messageService.removeMessagePin(message, ext);

Get a list of PIN messages

  • API prototype
  /// 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
await 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
class MessageService {
  /// Notifications for events of PIN messages
  Stream<NIMMessagePinEvent> get onMessagePinNotify;
}
  • NIMMessagePinEvent representation
Parameter Type Description
pin NIMMessagePin PIN message
  • Example
await 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
  ///
  /// 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
NimCore.instance.messageService.addStickTopSession(sessionId, sessionType, ext);

Delete a pinned session

  • API prototype
  ///
  /// 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
NimCore.instance.messageService.removeStickTopSession(sessionId, sessionType, ext);

Update the extension field of a pinned session

  • API prototype
  ///
  /// 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
NimCore.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
  ///
  /// Get the list of pinned sessions
  ///
  Future<NIMResult<List<NIMStickTopSessionInfo>>> queryStickTopSession()
  • Example
  NimCore.instance.messageService.queryStickTopSession();

Listen to the synchronization of pinned sessions

  • API prototype
  ///
  /// 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
  NimCore.instance.messageService.onSyncStickTopSession.listen((List<NIMStickTopSessionInfo> event) {
          });

Listen to new pinned sessions

  • API prototype
  ///
  /// 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
  NimCore.instance.messageService.onStickTopSessionAdd.listen((NIMStickTopSessionInfo event) {
          });

Listen to removing pinned sessions

  • API prototype
  ///
  /// 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
  NimCore.instance.messageService.onStickTopSessionRemove.listen((NIMStickTopSessionInfo event) {
          });

Listen to updating pinned sessions

  • API prototype
  ///
  /// 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
  NimCore.instance.messageService.onStickTopSessionUpdate.listen((NIMStickTopSessionInfo event) {
          });
Was this page helpful?
Yes
No
  • Replies
  • Reply
  • Query chat threads in the cloud
  • Get the number of replies in a thread
  • Quick comment
  • Add a quick comment
  • Delete a quick comment
  • Get a quick comment
  • Listen for new comments
  • Listen for deleting quick comment
  • Bookmarks
  • Add a bookmark
  • Remove multiple bookmark messages at a time
  • Update the extension field of the bookmark
  • Query paginated bookmarks
  • PIN tag
  • Add a PIN tag to a message
  • Update a PIN message
  • Remove the PIN tag of a message
  • Get a list of PIN messages
  • Listen for events of PIN messages
  • Pinned sessions
  • Add a pinned session
  • Delete a pinned session
  • Update the extension field of a pinned session
  • Get the pinned sessions
  • Listen to the synchronization of pinned sessions
  • Listen to new pinned sessions
  • Listen to removing pinned sessions
  • Listen to updating pinned sessions