Update time: 2023/03/23 09:06:29

System notification overview

The CommsEase built-in system notifications are categorized into pre-defined built-in system notifications and custom system notifications.

Built-in system notifications

Built-in system notifications delivered by the CommsEase server to users or groups are used for system events. Built-in system notifications are received and stored in the SDK with simple unread count implementation.

The built-in system notification are sent for events in advanced groups, such as join requests and invitations. For specific types of events, see [NIMSysMsgType](https://doc.yunxin.163.com/docs /interface/Windows side of instant messaging/NIMSDKAPI_CPP/html/nim__sysmsg__def_8h.html#aca66cca1d454dc8938338ebd5ec08561). If your app also allows CommsEase to manage friend relationships, notifications for adding and deleting belongs to type.

Built-in system notifications are displayed in the list of verification messages. For example: XX sent a friend request.

Built-in system notifications and notification messages

Notification messages are in-session messages (kNIMMessageTypeNotification ). The notification messages can be received when a user is online or offline or synchronized when a user logs in on a new device. Notification messages are used for events in advanced groups, supergroups, and chat rooms. For more information, see NIMNotificationId. Notification messages are not counted as unread. Push service and notification bar alerts are not supported. Notification messages are located in the middle of the chat interface. For example: group name update, XX ledt the group chat.

Custom system notifications

Custom system notification can be delivered from clients or the app server. The SDK only transparently transmits custom system notifications, and does not parse and store them. The content of a notification can be customized.

You can send custom notifications for some events based on your business logic to implement various types of business scenarios. For example, the "typing" indicator of a user in a one-on-one chat.

Built-in system notifications and custom system notifications

Custom system notifications are in-session messages (kNIMMessageTypeCustom) that allows you to customize messages when a user is online or offline with alerts or synchronized when a user logs in on a new device. Custom messages are the same as text and voice messages, and are located on the left and right sides of the chat interface. For example, guessing games, stickers, and disappearing messages are implemented with custom messages.

System notification

Type Storage Unread count Online messaging Offline push Message sync Push notification
Built-in system notifications Yes Yes Yes No No
Custom system notifications No No Yes No Yes

System notification object

The system notification object is defined in nim::SysMessage. Parameters:

Parameter Description
timetag The timestamp when a system notification is sent
Type Type of events for which built-in system notifications are sent. For more information, see NIMSysMsgType
sender_accid The sender source of the system notification, account or group ID
receiver_accid The target of system notification, account or group ID
id The ID of a system notification, the unique identifier of the system notification
content The content of a system notification, read-only, SDK does not forward this field.
attach The attachment of a system message.
status The status of a system notification, unread, read, passed, rejected, deleted and expired. For more information, see NIMSysMsgStatus
msg_setting The configuration of a system notification, such as whether the system notification are delivered as push notification, counted as unread, whether the sytem notification are delivered when the target user is offline. For more information, see SysMessageSetting
rescode The error code for sending a system notification. For more information, see NIMResCode
feature System notification type, divided into offline, synchronous, and default.. For more information, see NIMMessageFeature
Total_unread_count Total unread count of system notifications
Client_msg_id Client ID of a system notification
callbac_ext Custom field for webhook, valid for SDKv8.2.0 and later.

Types of system notifications

The built-in system notifications are avaiilable for the following events:

Type Description
kNIMSysMsgTypeTeamInvite Invite a user to join an advanced group
kNIMSysMsgTypeTeamApply Request to join an advanced group
kNIMSysMsgTypeTeamInviteReject Reject to join an advanced group.
kNIMSysMsgTypeTeamReject Reject a request to join request
kNIMSysMsgTypeFriendAdd Add a friend. The kNIMSysMsgKeyAttach: {"vt":verifyType} returns the specific verification type.
kNIMSysMsgTypeFriendDel Delete a friend
kNIMSysMsgTypeCustomP2PMsg Custom system notifications for one-on-one chats
kNIMSysMsgTypeCustomTeamMsg Custom system notifications for advanced groups
kNIMSysMsgTypeCustomSuperTeamMsg Custom system notifications for supergroups
kNIMSysMsgTypeUnknown Unknown type, used for local behaviors, irgored by default.

SDK's custom system notifications do not count as unread even if the count parameter is configured (kNIMSysMsgKeyPushNeedBadge=1).

System notification APIs


The nim::SystemMsg interfaces to handle system notification.


The nim_sysmsg interfaces to handle system notification.


The NIM.SysMessage.SysMsgAPI interfaces to handle system notification.

Was this page helpful?
  • System notification overview
  • Built-in system notifications
  • Custom system notifications
  • System notification
  • System notification object
  • Types of system notifications
  • System notification APIs