Manage Built-in System Notifications
Update time: 2023/03/23 09:19:21
NIM SDK receives and stores built-in system notifications. You are allowed to handle, query, delete built-in system notifications and set status of built-in system notifications.
How it works
Built-in system notifications delivered by the CommsEase server to users or groups used for system events.
The APIs to manipulate system notifications are defined in nim::SystemMsg. For more information, see nim::SystemMsg.
The previous module are implemented in C++. For the implementation in C language, see nim_sysmsg. For the implementation in C# language, see NIM.SysMessage.SysMsgAPI.
Listener for system notifications
Only after registering the listener for events of built-in system notification, users will receive the corresponding system notifications.

Use the callback template (ReceiveSysmsgCallback) and call the RegSysmsgCb method to listen to the system events.
In addition to the callback template (ReceiveSysmsgCallback), the SDK also provides the following callback templates:
QueryMsgCallback: Query system notificationsNotifySysmsgResCallback: Modify the system notificationQuerySysmsgUnreadCallback: Query the number of unread system notifications.ReadAllCallback: Mark all system notifications read.DeleteAllCallback: Delete all system notifications.BatchSetCallback: Set multiple system notifications.NotifySingleSysmsgCallback: Edit one system notificationSetStatusCallback: Set the status of a system notificationDeleteCallback: Delete a system notificationSendCustomSysmsgCallback: Send custom notifications
Sample code:
cppvoid UIReceiveSysmsgCallback(nim::SysMessage& msg)
{
if (msg.type_ == nim::kNIMSysMsgTypeCustomP2PMsg || msg.type_ == nim::kNIMSysMsgTypeCustomTeamMsg)
{
}
else
{
}
}
void foo()
{
nim::SystemMsg::RegSysmsgCb(&OnReceiveSysmsgCallback);
}
Use the callback function definition (nim_sysmsg_receive_cb_func) and call the nim_sysmsg_reg_sysmsg_cb method to listen to the system events.
Sample code:
cppvoid CallbackSysmsgChange(const char *result, const char *json_extension, const void *callback)
{
//Parse the result
}
typedef void(*nim_sysmsg_reg_sysmsg_cb)(const char *json_extension, nim_sysmsg_receive_cb_func cb, const void* user_data);
void foo()
{
nim_sysmsg_reg_sysmsg_cb func = (nim_sysmsg_reg_sysmsg_cb) GetProcAddress(hInst, "nim_sysmsg_reg_sysmsg_cb");
func("", &CallbackSysmsgChange, nullptr);
}
The registered callback sends a notification to the APP. To ensure the consistency of the entire program logic, the APP must perform corresponding operations for different types of system notifications.
The built-in system notifications are available 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 |
kNIMSysMsgTypeUnknown |
Unknown type, used for local behaviors, irgored by default. |
Query built-in system notifications
Query built-in system notifications in the local database by calling the QueryMsgAsync method
Parameters:
| Parameter | Description |
|---|---|
| last_time | The timestamp of the message queried last time. |
| limit_count | The number of system notifications returned in this query, the maximum and default value are 100. |
| json_extension | Extension in JSON. |
| Cb | callback for the result, the returned list is sorted in descending order by time. |
Sample code:
cppvoid LoadEventsCb(int count, int unread, const std::list<nim::SysMessage> &result)
{
}
void foo()
{
nim::SystemMsg::QueryMsgAsync(20, 0, &LoadEventsCb);
}
The SDK stores built-in system notifications in the database.
:::
Query built-in system notifications in the local database by calling the nim_sysmsg_query_msg_async method.
Sample code:
cppvoid CallbackSysmsgChange(int count, const char *result, const char *json_extension, const void *callback)
{
//Parse the result
}
typedef void(*nim_sysmsg_query_msg_async)(int limit_count, __int64 last_time, const char *json_extension, nim_sysmsg_query_cb_func cb, const void* user_data);
void foo()
{
nim_sysmsg_query_msg_async func = (nim_sysmsg_query_msg_async) GetProcAddress(hInst, "nim_sysmsg_query_msg_async");
func(20, 0, "", &CallbackSysmsgChange, nullptr);
}
Delete built-in system notifications
Delete all built-in system notifications
Delete all built-in system notifications by calling the DeleteAllAsync method. Sample code:
cppvoid DeleteAllCb(nim::NIMResCode res_code, int unread)
{
}
void foo()
{
nim::SystemMsg::DeleteAllAsync(&DeleteAllCb);
}
Delete all built-in system notifications nim_sysmsg_delete_all_async method. Sample code:
cppvoid CallbackNotifySysmsgRes(int res_code, int unread_count, const char *json_extension, const void *callback)
{
}
typedef void(*nim_sysmsg_delete_all_async)(const char *json_extension, nim_sysmsg_res_cb_func cb, const void *user_data);
void foo()
{
nim_sysmsg_delete_all_async func = (nim_sysmsg_delete_all_async) GetProcAddress(hInst, "nim_sysmsg_delete_all_async");
func("", &CallbackNotifySysmsgRes, nullptr);
}
Delete specified built-in system notifications
Delete specified built-in system notifications by notification ID by calling the DeleteAsync method. Sample code:
cppvoid DeleteCb(nim::NIMResCode code, __int64 msg_id, int unread)
{
}
void foo(__int64 msg_id)
{
nim::SystemMsg::DeleteAsync(msg_id, &DeleteCb);
}
Delete specified built-in system notifications by notification ID by calling the nim_sysmsg_delete_async method. Sample code:
cvoid CallbackNotifySingleSysmsg(int res_code, __int64 msg_id, int unread_count, const char *json_extension, const void *callback)
{
}
typedef void(*nim_sysmsg_delete_async)(__int64 msg_id, const char *json_extension, nim_sysmsg_res_ex_cb_func cb, const void *user_data);
void foo(__int64 msg_id)
{
nim_sysmsg_delete_async func = (nim_sysmsg_delete_async) GetProcAddress(hInst, "nim_sysmsg_delete_async");
func(msg_d, "", &CallbackNotifySingleSysmsg, nullptr);
}
Delete built-in system notifications of specified type
Delete built-in system notifications of specified type by calling the DeleteByTypeAsync method.
For information about types of system notifications, see NIMSysMsgType .
Sample code:
cppSystemMsg::DeleteByTypeAsync(kNIMSysMsgTypeTeamApply, [](NIMResCode res_code, int unread_count) {
// Handle responses
});
Delete built-in system notifications of specified type by calling the nim_sysmsg_delete_logs_by_type_async method.
For information about types of system notifications, see NIMSysMsgType.
Sample code:
cppvoid DeleteByTypeCallback(int res_code, int unread_count, const char* json_extension, const void* callback){
}
nim_sysmsg_delete_logs_by_type_async(kNIMSysMsgTypeTeamApply, "", &DeleteByTypeCallback, NULL);
Set the status of system notifications
The status of system notifications are defined in NIMSysMsgStatus . The following states are supported.
kNIMSysMsgStatusNone: Unread, by defaultkNIMSysMsgStatusRead: ReadkNIMSysMsgStatusPass: PassedkNIMSysMsgStatusDecline: RejectedkNIMSysMsgStatusDeleted: DeletedkNIMSysMsgStatusInvalid: Invalid
Set the status of the specified built-in system notifications
Set the status of the specified built-in system notifications by notification ID by calling the SetStatusAsync method. Sample code:
cppvoid SetStatusCb(nim::NIMResCode code, __int64 msg_id, int unread)
{
}
void foo(__int64 msg_id)
{
nim::SystemMsg::SetStatusAsync(msg_id_, nim::kNIMSysMsgStatusInvalid, &SetStatusCb);
}
Fields will only be updated in the local database, not on the server.
:::
Set the status of the specified built-in system notifications by calling the nim_sysmsg_set_status_async method. Sample code:
cvoid CallbackNotifySingleSysmsg(int res_code, __int64 msg_id, int unread_count, const char *json_extension, const void *callback)
{
}
typedef void(*nim_sysmsg_set_status_async)(__int64 msg_id, nim::NIMSysMsgStatus status, const char *json_extension, nim_sysmsg_res_ex_cb_func cb, const void* user_data);
void foo(__int64 msg_id, nim::NIMSysMsgStatus status)
{
nim_sysmsg_set_status_async func = (nim_sysmsg_set_status_async) GetProcAddress(hInst, "nim_sysmsg_set_status_async");
func(msg_d, status, "", &CallbackNotifySingleSysmsg, nullptr);
}
Set the status of built-in system notifications of specified type
Set the status of built-in system notifications of specified type by calling the SetStatusByTypeAsync method. Sample code:
cppSystemMsg::SetStatusByTypeAsync(kNIMSysMsgTypeTeamApply, kNIMSysMsgStatusPass, [](NIMResCode res_code, int unread_count) {
// process response
// ...
});
- For information about types of system notifications, see
NIMSysMsgType. - Fields will only be updated in the local database, not on the server.
:::
Set the status of built-in system notifications of specified type by calling the nim_sysmsg_set_logs_status_by_type_async method. Sample code:
cstatic void CallbackNotifySysmsgRes(int res_code, int unread_count, const char* json_extension, const void* callback) {
// process response
// ...
}
nim_sysmsg_set_logs_status_by_type_async)(type, kNIMSysMsgStatusPass, "", &CallbackNotifySysmsgRes, NULL);
API reference
API |
Description |
|---|---|
RegSysmsgCb |
Listen to the event of receiving system notifications. |
QueryMsgAsync |
Query all local built-in system notifications. |
DeleteAllAsync |
Delete all local built-in system notifications. |
DeleteAsync |
Delete specified built-in system notifications by notification ID. |
DeleteByTypeAsync |
Delete built-in system notifications of specified type. |
SetStatusAsync |
Set the status of a specified built-in system notification by notification ID. |
SetStatusByTypeAsync |
Set the status of system notifications of specified type. |
API |
Description |
|---|---|
nim_sysmsg_reg_sysmsg_cb |
Listen to the event of receiving system notifications. |
nim_sysmsg_query_msg_async |
Query all local built-in system notifications. |
nim_sysmsg_delete_all_async |
Delete all local built-in system notifications. |
nim_sysmsg_delete_async |
Delete specified built-in system notifications by notification ID. |
nim_sysmsg_delete_logs_by_type_async |
Delete built-in system notifications of specified type. |
nim_sysmsg_set_status_async |
Set the status of a specified built-in system notification by notification ID. |
nim_sysmsg_set_logs_status_by_type_async |
Set the status of system notifications of specified type. |





