System notifications

System notification overview

System notification is a built-in message/notification and its corresponding data structure is SystemMessage. The notification messages delivered by the CommsEase server to users are used for system event notifications. Notifications of group changes, such as group join requests, group invitation and more. If your apps also manage friend relationships, notifications for adding and deleting friends also belong to this type. System notifications are received and stored by the SDK, and provide simpler unread management.

SystemMessage representation

Field	Type	Description
attach	String?	The attachment of a system message.
attachObject	Object?	The parsed object of the attachment of a system notification.
content	String?	The content of a system notification
customInfo	String?	the custom information. The custom information is applied for sending invitations to join a group.
fromAccount	String?	the account that sends a system notification
messageId	int?	The ID of a system notification.
status	SystemMessageStatus?	The status of a system notification.
targetId	String?	The ID of the recipient that receives the system notification.
Time	int?	The time when a system notification is sent in milliseconds.
type	SystemMessageType?	The type of a system notification.
Unread	bool?	Whether a system notification is read.

Listener for system notifications

Listener for the event of system notifications.

• API prototype

dart
 /// Register or unregister the observer for receiving system notifications
 /// [observer] The observer. The parameter is the received system message.
 /// [register] true: register; false: unregister
 
Stream<SystemMessage> get onReceiveSystemMsg

The callback is unavailable for web apps.

• Example

dartNimCore.instance.systemMessageService.onReceiveSystemMsg.  NimCore.instance.systemMessageService.onReceiveSystemMsg.listen((SystemMessage event) {

        });

Get a system notification

Get a system notification (Android)

• API prototype

dart/// Query the list of system notifications, only applicable to Android apps
Future<NIMResult<List<SystemMessage>>> querySystemMessagesAndroid(int offset,int limit);

• Parameters

Parameter	Type	Description
offset	int	Specify an offset from where to start returning data.
limit	int	The limit of the returned entries from a query.

• Example

dart// Starting from the first message, query 10 system messages
final result = await NimCore.instance.systemMessageService
              .querySystemMessagesAndroid(1,10);

Get a system notification

• API prototype

dart /// Get a system notification (iOS, macOS, and Windows)
Future<NIMResult<List<SystemMessage>>> querySystemMessagesIOSAndDesktop(SystemMessage systemMessage,int limit);

• Parameters

Parameter	Type	Description
systemMessage	SystemMessage	The earliest system notification. Pass null if no system notifications are sent.
limit	int	The limit of the returned entries from a query.

Get system notifications of a specified type (Android)

The SystemMessageType collection of system message types needs to be passed.

• API prototype

dart /// Query the list of system notifications by type, only applicable to Android apps.
Future<NIMResult<List<SystemMessage>>> querySystemMessageByTypeAndroid(
      List<SystemMessageType> types, int offset, int limit);

• Parameters

Parameter	Type	Description
types	List<SystemMessageType>	The types of system notifications to be queried
offset	int	Specify an offset from where to start returning data.
limit	int	Specify the limit of the number of results that are returned.

• Example

1. Sync method

dartList<SystemMessageType> systemMessageTypeList = [SystemMessageType.addFriend];

// Only query the system notifications of the "add friend" type, start from the beginning, and query 3 system notifications
final result = await NimCore.instance.systemMessageService
              .querySystemMessageByTypeAndroid(systemMessageTypeList,
                  inputParams['offset'] as int, inputParams['limit'] as int);

Get system notifications of a specified type (iOS, macOS, and Windows)

The SystemMessageType collection of system message types needs to be passed.

• API prototype

dart
 /// Get system notifications of a specified type (iOS, macOS, and Windows)
Future<NIMResult<List<SystemMessage>>> querySystemMessageByTypeIOSAndDesktop(
     SystemMessage systemMessage,List<SystemMessageType> types,int limit);

• Parameters

Parameter	Type	Description
types	List<SystemMessageType>	The types of system notifications to be queried
systemMessage	SystemMessage	The earliest system notification. Pass null if no system notifications are sent.
limit	int	Specify the limit of the number of results that are returned.

Get unread system messages

dart
 /// Get all unread system messages
 
Future<NIMResult<List<SystemMessage>>> querySystemMessageUnread();

Get the unread count of system notifications

Listen to changes of unread count

This interface can monitor changes in the total unread count of system messages.

• API prototype

dart
 /// Register or unregister the observer for changes of unread count of system messages
 
  final StreamController<int> onUnreadCountChange =
      StreamController<int>.broadcast();

• Example

dartNimCore.instance.systemMessageService.onUnreadCountChange.listen((int event) {

});

Get the unread count

Query the number of unread system messages

• API introduction

The unread field in SystemMessage is used to mark whether the system notification is unread, and this function will return the total number of all unread system notifications.

• API prototype

dart /// Query the number of unread system messages

Future<NIMResult<int>> querySystemMessageUnreadCount();

• Example

dartfinal result = await NimCore.instance.systemMessageService
              .querySystemMessageUnreadCount();

Get the number of unread system messages of specified type

• API prototype

dart
 /// Get the number of unread system notifications of a specified type
 ///
 /// [types] types of system notifications
 /// @return the number of unread system messages of a specified type
 
Future<NIMResult<int>> querySystemMessageUnreadCountByType(
      List<SystemMessageType> types);

• Example

dartList<SystemMessageType> systemMessageTypeList = [SystemMessageType.addFriend];

// Get the number of unread system messages of"add friend" type
final result = await NimCore.instance.systemMessageService
              .querySystemMessageUnreadCountByType(systemMessageTypeList);

Mark as read

Mark all system notifications as read

After this function is called, the number of unread system notifications will be reset to 0.

• API prototype

dart
 /// Set all system messages to read and reset the number of the unread system messages to 0.
 
Future<NIMResult<void>> resetSystemMessageUnreadCount()

• Example

dart// After viewing the system notification list, you can call this function to set the unread value to 0
final result = await NimCore.instance.systemMessageService
              .resetSystemMessageUnreadCount();

Mark all system notifications of a specified type as read

• API prototype

dart
 /// Set system messages of a specified type to read
 ///
 /// [types] types of system notifications
 
Future<NIMResult<void>> resetSystemMessageUnreadCountByType(
      List<SystemMessageType> types);

• Example

dartList<SystemMessageType> systemMessageTypeList = [SystemMessageType.addFriend];

// Set system notifications of "add friend" type to read
final result = await NimCore.instance.systemMessageService
              .resetSystemMessageUnreadCountByType(systemMessageTypeList);

Mark a system notification as read

• API prototype

dart
 /// Set a system message to read
 ///
 /// [messageId] The ID of a system notification.
 
Future<NIMResult<void>> setSystemMessageRead(int messageId);

• Example

dartfinal result = await NimCore.instance.systemMessageService
              .setSystemMessageRead(messageId);

Delete system notifications

Delete all system notifications

Delete all the system messages..

• API prototype

dart
 /// Delete all system notifications
 
Future<NIMResult<void>> clearSystemMessages();

• Example

dartfinal result = await NimCore.instance.systemMessageService.clearSystemMessages();

Deleted system notifications of a specified type

Delete system messages of a specified type. See SystemMessageType for types.

• API prototype

dart
 /// Delete system notifications of a specified type.
 ///
 
Future<NIMResult<void>> clearSystemMessagesByType( List<SystemMessageType> types);

• Parameters

Parameter	Type	Description
types	List<SystemMessageType>	The types of system notifications.

• Example

dartList<SystemMessageType> systemMessageTypeList = [SystemMessageType.addFriend];

// Delete system notifications of "add friend" type
final result = await NimCore.instance.systemMessageService
              .clearSystemMessagesByType(systemMessageTypeList);

Delete a system notification

• API prototype

dart
 /// Delete a system notification.
 ///
 /// [messageId] The ID of a specified system notification.
 
Future<NIMResult<void>> deleteSystemMessage(int messageId);

• Example

dart final result = await NimCore.instance.systemMessageService
              .deleteSystemMessage(messageId);

Set the state of system messages

• API introduction

For the system notification status enumeration, see SystemMessageStatus. In addition to providing five built-in statuses: unhandled, passed, rejected, ignored, and expired, five custom extension types are provided for third-party developers use. After the user has processed the system notification, call setSystemMessageStatus to update the system notification status.

• API prototype

dart
 /// Set the status of system notifications. After system notifications are handled, the method can be called to update the state of system notifications.
 ///
 
Future<NIMResult<void>> setSystemMessageStatus(
      int messageId, SystemMessageStatus status);

• Parameters

Parameter	Type	Description
messageId	int	The ID of a system notification.
status	SystemMessageStatus	The status of a system notification to be updated

SystemMessageStatus attributes

Parameter	Type	Description
declined	Enum type	The notification is declined.
expired	Enum type	The notification is expired.
extension1	Enum type	Custom enum type 1
extension2	Enum type	Custom enum type 2
extension3	Enum type	Custom enum type 3
extension4	Enum type	Custom enum type 4
extension5	Enum type	Custom enum type 5
ignored	Enum type	The system notification is ignored.
init	Enum type	The initial status of a system notification.
passed	Enum type	The system notification is handled.

• Example

dart// Set the state of system messages to expired
SystemMessageStatus status = SystemMessageStatus.expired;
final result = await NimCore.instance.systemMessageService
              .setSystemMessageStatus(message.getMessageId(), status);

Custom system notifications

In addition to the built-in system notification, the NIM SDK also provides an additional custom system to facilitate the notification of business logic, such as that the peer is typing.... This notification can be initiated by either the client or the app server.

Note that custom messages belongs to the messaging system of CommsEase, which is suitable for conversations, stored in the message database by the SDK, and displayed to users together with other built-in message types of CommsEase. Custom notifications are used for third-party event status notifications, and the SDK does not store, count unread counts, or parse these notifications. The SDK transmits and notify these events. The upper layer of your app can handle the persistence of custom notifications.

CustomNotiication is used.to handle custom notifications.

CustomNotification interface

Parameter	Type	Description
apnsText	String	The body of a push notification.
config	CustomNotificationConfig	Options for configure custom notifications. For more information, see CustomNotificationConfig
content	String	The content of a custom notification.
fromAccount	String	The account that sends a specified notification.
nIMAntiSpamOption	NIMAntiSpamOption	The content moderation configuration.
pushPayload	Map<String, Object>	The payload object for a push notification.
sessionId	String	The ID of a chat object (friend account or group ID).
sessionType	SessionTypeEnum	Session type
time	int	Time when a notification is sent in milliseconds.
sendToOnlineUserOnly	bool	Whether a notification is sent only to onle users or groups.

CustomNotificationConfig representation

Field	Type	Description
enablePush	bool	Whether a notification is delivered using the push service (including message alerts on Android.). The default value is true.
enablePushNick	bool	Whether a notification requires the nickname in the push notification (for iOS apps only). If the value is set to false, the nickname will not be displayed on iOS devices when the notification is received. The default value is false
enableUnreadCount	bool	Whether a notification is counted as unread. If the value is set to true, the option changes the unread count when the notification is received. The default value is true

Send a custom system notification

• API prototype

dart
 /// Send a custom system notification
 /// The SDK sends the message in pass-through mode, the status of the custom system notification is not be recorded. However, you can set a callback to track the result of the operation.
 ///
 /// [notification] custom notification
 
Future<NIMResult<void>> sendCustomNotification(CustomNotification notification);

• Example

dart

// Add the content of a notification. For scalability, the JSON format is used and "id" is used as the type.
JSONObject json = new JSONObject();
json.put("id", "2");
JSONObject data = new JSONObject();
data.put("body", "the_content_for_display");
data.put("url", "url_of_the_game_or_anything_else");
json.put("data", data);

// configure CustomNotificationConfig
CustomNotificationConfig config = CustomNotificationConfig(enablePush:true,enableUnreadCount:true);

// Create a custom system notification and specify the recipients
CustomNotification notification = CustomNotification(sessionId: receiverId,sessionType:sessionType,content: json.toString(),apnsTest:"the_content_for_apns",config:config)


// Send a custom notification
final result = await NimCore.instance.systemMessageService
              .sendCustomNotification(notification);

Receive custom system notifications

• API prototype

dart
 /// Register or unregister the observer for receiving custom notifications
 /// [observer] The observer. The parameter is the received custom message.
 /// [register] true: register; false: unregister
 
final StreamController<CustomNotification> onCustomNotification =
      StreamController<CustomNotification>.broadcast();

• Example

dartNimCore.instance.systemMessageService.onCustomNotification.listen((CustomNotification event) {

});