System Notification

Update time: 2022/06/23 11:25:04

In addition to the message channel, IM SDK also provides a system notification channel for delivering notifications other than messages. There are currently two types: built-in system notification and user-defined system notification.

All built-in system notifications and user-defined system notifications are sent using registered callbacks.

C++

void UIReceiveSysmsgCallback(nim::SysMessage& msg)
{
	if (msg.type_ == nim::kNIMSysMsgTypeCustompeer-to-peerMsg || msg.type_ == nim::kNIMSysMsgTypeCustomTeamMsg)
	{

	}
	else
	{

	}
}

void foo()
{
	nim::SystemMsg::RegSysmsgCb(&OnReceiveSysmsgCallback);
}

C#

void OnReceivedSysNotification(object sender, NIMSysMsgEventArgs e)
{
    if (e.Message == null || e.Message.Content == null)
        return;

    if (e.Message.Content.MsgType == NIMSysMsgType.kNIMSysMsgTypeTeamInvite)
    {
        
    }
}

void foo()
{
	NIM.SysMessage.SysMsgAPI.ReceiveSysMsgHandler += OnReceivedSysNotification;
}

C

void CallbackSysmsgChange(const char *result, const char *json_extension, const void *callback)
{
	// parse 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);
}

to the APP. To ensure consistent logic of the program, app needs to perform operations correspondingly with different types of system notifications.

Built-in system notification

This is a type of notification predefined by the SDK, Currently, only applicable to several team operations, such as being invited to team. SDK is responsible for the persistence of these notifications.

In addition, IM SDK provides the following interfaces for getting and maintaining the record of built-in system notification:

Search the system notification list (searched in reverse order of time, sorted in reverse order):

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

C++

void LoadEventsCb(int count, int unread, const std::list<nim::SysMessage> &result)
{

}

void foo()
{
	nim::SystemMsg::QueryMsgAsync(20, 0, &LoadEventsCb);
}

C#

NIM.SysMessage.SysMsgAPI.QueryMessage(100, 0, (r) =>
{

});

C

void CallbackSysmsgChange(int count, const char *result, const char *json_extension, const void *callback)
{
	// parse 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);
}

Search unread count:

void nim_sysmsg_query_unread_count(const char *json_extension, nim_sysmsg_res_cb_func cb, const void *user_data);

C++

void OnQuerySysmsgUnreadCb(nim::NIMResCode res_code, int unread_count)
{
	if (res_code == 200)
		···
}

void foo()
{
	nim::SystemMsg::QueryUnreadCount(&OnQuerySysmsgUnreadCb);
}

C#

NIM.SysMessage.SysMsgAPI.QueryUnreadCount((response, count) =>
{

});

C

void CallbackNotifySysmsgRes(int res_code, int unread_count, const char *json_extension, const void *callback)
{
	
}

typedef void(*nim_sysmsg_query_unread_count)(const char *json_extension, nim_sysmsg_res_cb_func cb, const void *user_data);

void foo()
{
	nim_sysmsg_query_unread_count func = (nim_sysmsg_query_unread_count) GetProcAddress(hInst, "nim_sysmsg_query_unread_count");
	func("", &CallbackNotifySysmsgRes, nullptr);
}

Set message status:

void nim_sysmsg_set_status_async(__int64 msg_id, NIMSysMsgStatus status, const char *json_extension, nim_sysmsg_res_ex_cb_func cb, const void *user_data);

C++

void SetStatusCb(nim::NIMResCode code, __int64 msg_id, int unread)
{
	
}

void foo(__int64 msg_id)
{
	nim::SystemMsg::SetStatusAsync(msg_id_, nim::kNIMSysMsgStatusInvalid, &SetStatusCb);
}

C#

void foo(long msg_id)
{
    NIM.SysMessage.SysMsgAPI.SetMsgStatus(msg_id, NIM.SysMessage.NIMSysMsgStatus.kNIMSysMsgStatusRead, 
        (res_code, _msg_id, unread_count, json_extension, user_data) =>
    {

    });
}

C

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

Delete a message:

void nim_sysmsg_delete_async(__int64 msg_id, const char *json_extension, nim_sysmsg_res_ex_cb_func cb, const void *user_data);

C++

void DeleteCb(nim::NIMResCode code, __int64 msg_id, int unread)
{

}

void foo(__int64 msg_id)
{
	nim::SystemMsg::DeleteAsync(msg_id, &DeleteCb);
}

C#

void foo(long msg_id)
{
    NIM.SysMessage.SysMsgAPI.DeleteByMsgId(msg_id,
        (res_code, _msg_id, unread_count, json_extension, user_data) =>
    {

    });
}

C

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

Set all messages as read:

void nim_sysmsg_read_all_async(const char *json_extension, nim_sysmsg_res_cb_func cb, const void *user_data);

C++

void SysMsgReadAllCb(nim::NIMResCode code, int unread)
{

}

void foo()
{
	nim::SystemMsg::ReadAllAsync(&SysMsgReadAllCb);
}

C#

void foo()
{
    NIM.SysMessage.SysMsgAPI.SetAllMsgRead(
        (res_code, unread_count, json_extension, user_data) =>
    {

    });
}

C

void CallbackNotifySysmsgRes(int res_code, int unread_count, const char *json_extension, const void *callback)
{
	
}

typedef void(*nim_sysmsg_read_all_async)(const char *json_extension, nim_sysmsg_res_cb_func cb, const void* user_data);

void foo()
{
	nim_sysmsg_read_all_async func = (nim_sysmsg_read_all_async) GetProcAddress(hInst, "nim_sysmsg_read_all_async");
	func("", &CallbackNotifySysmsgRes, nullptr);
}

Delete all messages:

void nim_sysmsg_delete_all_async(const char *json_extension, nim_sysmsg_res_cb_func cb, const void *user_data);

C++

void DeleteAllCb(nim::NIMResCode res_code, int unread)
{

}

void foo()
{
	nim::SystemMsg::DeleteAllAsync(&DeleteAllCb);
}

C#

void foo()
{
    NIM.SysMessage.SysMsgAPI.DeleteAll(
        (res_code, unread_count, json_extension, user_data) =>
    {

    });
}

C

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

User-defined system notification

In addition to built-in system notification, SDK also provides a custom system for developers to facilitate the notification of business logic. The notification may be issued by either the client or the developer server.

The format of custom notification send from client is defined by the developer (in kNIMSysMsgKeyAttach), and SDK is only responsible for sending and receiving the notification online or offline, including peer-to-peer notification and team notification, without any parsing or storage. Therefore, such notification will not be reflected in chat history, and it is applicable to scenes such as sending the status of typing. Sample codes:

C++

void foo()
{
	Json::Value json;
	Json::FastWriter writer;
	json["id"] = "1";

	nim::SysMessage msg;
	msg.recipient_accid_ = ;	//recipient id
	msg.sender_accid_ = ; 	//sender id
	msg.client_msg_id_ = QString::GetGUID();	//local message id
	msg.attach_ = writer.write(json);			//notification attachment content
	msg.type_ = nim::kNIMSysMsgTypeCustompeer-to-peerMsg; //notification type

	nim::SystemMsg::SendCustomNotificationMsg(msg.ToJsonString());
}

C#

void foo()
{
	NIM.SysMessage.NIMSysMessageContent content = new NIM.SysMessage.NIMSysMessageContent();
	content.ClientMsgId = Guid.NewGuid().ToString();
	content.ReceiverId = ""; //recipient id
	content.SenderId = ""; //sender id
	if (_sessionType == NIM.Session.NIMSessionType.kNIMSessionTypepeer-to-peer)
	    content.MsgType = NIM.SysMessage.NIMSysMsgType.kNIMSysMsgTypeCustompeer-to-peerMsg; //notification type
	else if (_sessionType == NIM.Session.NIMSessionType.kNIMSessionTypeTeam)
	    content.MsgType = NIM.SysMessage.NIMSysMsgType.kNIMSysMsgTypeCustomTeamMsg;
	content.Attachment = ""; //notification attachment content
	NIM.SysMessage.SysMsgAPI.SendCustomMessage(content);
}

C

typedef void(*nim_sysmsg_send_custom_notification)(const char *json_msg, const char *json_extension);

void foo()
{
	//json_msg: key definition is detailed in system message field nim_sysmsg_def.h
	Json::Value json_msg;
	json_msg[kNIMSysMsgKeyToAccount] = ; // recipient id
	json_msg[kNIMSysMsgKeyFromAccount] = ; // sender id
	json_msg[kNIMSysMsgKeyLocalClientMsgId] = local message id; 
	json_msg[kNIMSysMsgKeyTime] = ; //timestamp
	json_msg[kNIMSysMsgKeyAttach] = ; //notification attachment content
	json_msg[kNIMSysMsgKeyType] = ; //notification type

	nim_sysmsg_send_custom_notification func = (nim_sysmsg_send_custom_notification) GetProcAddress(hInst, "nim_sysmsg_send_custom_notification");
	func(json_msg.toStyledString().c_str(), nullptr);
}

Receipt of custom notification send from the client is notified in advance by the app to the developer via

void nim_sysmsg_reg_sysmsg_cb(const char *json_extension, nim_sysmsg_receive_cb_func cb, const void *user_data);

registered callback. Sample codes:

C++

void OnReceiveSysmsgCallback( const nim::SysMessage& msg )
{
	
}

void foo()
{
	nim::SystemMsg::RegSysmsgCb(&OnReceiveSysmsgCallback);
}

C#

void OnReceivedSysNotification(object sender, NIMSysMsgEventArgs e)
{
    if (e.Message == null || e.Message.Content == null)
        return;

    if (e.Message.Content.MsgType == NIMSysMsgType.kNIMSysMsgTypeTeamInvite)
    {
        ···
    }
}

void foo()
{
	NIM.SysMessage.SysMsgAPI.ReceiveSysMsgHandler += OnReceivedSysNotification;
}

C

void CallbackSysmsgChange(const char *result, const char *json_extension, const void *callback)
{
	// parse 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);
}

User-defined system notification also has the following property settings:

  • Whether to enable offline storage for custom notifications (kNIMSysMsgKeyCustomSaveFlag)
  • Push message text of custom notification (kNIMSysMsgKeyCustomApnsText)
  • Third-party custom push properties (kNIMSysMsgKeyPushPayload)
  • Whether to enable push (kNIMSysMsgKeyPushEnable)
  • Whether enable push notifications counting (kNIMSysMsgKeyNeedBadge)
  • Whether to add display name to push notifications (kNIMSysMsgKeyPushNeedNick)

The SDK is not responsible for the persistence of custom notifications, parsing and persisting of which should be done by app as needed based on its own business logic.

Was this page helpful?
Yes
No
  • Built-in system notification
  • User-defined system notification