In addition to the message channel, SDK also provides a system notification channel for distribution of notifications other than messages. There are currently two types: built-in system notification and custom system notification. System notifications mainly include team change notifications, such as application for joining team and team invitation. If the third-party app also hosts friendship, addition and removal of friends are also included into this type of notification. System notifications are received and stored by SDK that supports simple management of unread count. Push parameter settings are available when sending custom system notifications.

Note: The notifications of team joining application and invitation are different from the notifications of team operation results, such as those of creating a team, dismissing a team, removing members, inviting people into the team, etc. Notifications for team operations are delivered through the IM message channel (see team notification event for details).

SysMessageParameter description

Type	Parameter	Description
NIMResCode	kNIMSysMsgKeyLocalRescode	Notification error codes, please refer to NIMResCodefor details
NIMMessageFeature	kNIMSysMsgKeyLocalFeature	Notification attributes, with differences between offline, multi-terminal synchronization, roaming notifications, etc., see NIMMessageFeature for details.
int	kNIMSysMsgKeyLocalUnreadCount	Total number of unread notifications
string	kNIMSysMsgKeyLocalContent	Notification content, without json character string. For field definition, see NIMSysMessageContent.

NIMSysMessageContentParameter description

Type	Parameter	Description
int64_t	kNIMSysMsgKeyTime	Notification timestamp (in milliseconds), optional
int	kNIMSysMsgKeyType	Type of notification, such as team joining application, team joining invitation, add friend, etc., see NIMSysMsgType for details.
string	kNIMSysMsgKeyToAccount	Receiver id, user id if receiver is a user, or team id if receiver is a team, required
string	kNIMSysMsgKeyFromAccount	Sender id, optional in cases such as sending a custom notification
string	kNIMSysMsgKeyMsg	Notification P.S., to be completed as needed
string	kNIMSysMsgKeyAttach	Attachment, to be completed as needed, similar to the attachment content of ordinary IM messages, view the message sent.
int64_t	kNIMSysMsgKeyMsgId	Server message id (custom notification, value filled in must be 0), not required for the sender
int	kNIMSysMsgKeyLocalStatus	Locally defined system message status, refer to NIMSysMsgStatus, not required for the sender
string	kNIMSysMsgKeyLocalClientMsgId	Notification ID (client)
--	Message setting	The following field is a configured field in the message and also a part of notification content.
int	kNIMSysMsgKeyCustomSaveFlag	(Optional) Whether to enable offline save of the notification message: 0-Only send it to online users, 1- It can be sent to offline users
string	kNIMSysMsgKeyCustomApnsText	Push notification copy of custom system notification. If it is left blank, there is no push
int	kNIMSysMsgKeyPushEnable	(Optional) Whether push is needed, 0: not needed, 1: needed, set to 1 by default, should be used withkNIMSysMsgKeyCustomApnsText
int	kNIMSysMsgKeyPushNeedBadge	(Optional) Whether message count (corner mark) is needed, 0: not needed, 1: needed, set to 1 by default, should be used withkNIMSysMsgKeyCustomApnsText
int	kNIMSysMsgKeyPushNeedPrefix	(Optional) Whether nickname push is needed, 0: not needed, 1: needed, set to 0 by default, should be used withkNIMSysMsgKeyPushEnable
string	kNIMSysMsgKeyPushPayload	(Optional) Third-party custom push load content, must be an unformatted string that can be parsed as json, with a length of 2048
bool	kNIMSysMsgKeyAntiSpamEnable	(Optional) Whether to enable anti-spam of YiDun, set to false by default
string	kNIMSysMsgKeyAntiSpamContent	(Optional) Developer-defined anti-spam field, with a length limit of 5000 characters, should be used withkNIMSysMsgKeyAntiSpamEnable

NIMSysMessageContentParsing example:

//Assume that message is json object of the message content
void ParseSysMessageContent(Json::Value message)
{
    if (message.isObject())
    {
       int64_t timetag = message[kNIMSysMsgKeyTime].asUInt64();
       NIMSysMsgType type = (NIMSysMsgType)message[kNIMSysMsgKeyType].asUInt();
       char* receiver_accid = message[kNIMSysMsgKeyToAccount].asString();
       char* sender_accid = message[kNIMSysMsgKeyFromAccount].asString();
       char* content = message[kNIMSysMsgKeyMsg].asString();
       char* attach = message[kNIMSysMsgKeyAttach].asString();
       int64_t id = message[kNIMSysMsgKeyMsgId].asUInt64();
       NIMSysMsgStatus status = (NIMSysMsgStatus)message[kNIMSysMsgKeyLocalStatus].asUInt();

       //Parse message settings
       int push_need_badge = (BoolStatus)message[kNIMSysMsgKeyPushNeedBadge].asInt() == 1 ? BS_TRUE : BS_FALSE;
       int need_push = (BoolStatus)message[kNIMSysMsgKeyPushEnable].asInt() == 1 ? BS_TRUE : BS_FALSE;
       int push_need_prefix = (BoolStatus)message[kNIMSysMsgKeyPushNeedPrefix].asInt() == 1 ? BS_TRUE : BS_FALSE;
       int need_offline = (BoolStatus)message[kNIMSysMsgKeyCustomSaveFlag].asInt() == 1 ? BS_TRUE : BS_FALSE;
       char* push_payload = message[kNIMSysMsgKeyPushPayload].asString();
       char* push_content = message[kNIMSysMsgKeyCustomApnsText].asString();
       int anti_spam_enable = message[kNIMSysMsgKeyAntiSpamEnable].asInt() == 1 ? BS_TRUE : BS_FALSE;
       char* anti_spam_content = message[kNIMSysMsgKeyAntiSpamContent].asString();
       ...
    }
}

NIMSysMsgTypeDescription of notification type

Enumeration	Value	Description
kNIMSysMsgTypeTeamApply	0	Apply for joining team
kNIMSysMsgTypeTeamReject	1	Reject joining application
kNIMSysMsgTypeTeamInvite	2	Invite to team
kNIMSysMsgTypeTeamInviteReject	3	Reject invitation to join
kNIMSysMsgTypeFriendAdd	5	Add friend
kNIMSysMsgTypeFriendDel	6	Delete friend
kNIMSysMsgTypeCustomP2PMsg	100	Transparent transmission of p2p messages
kNIMSysMsgTypeCustomTeamMsg	101	Transparent transmission of team messages
kNIMSysMsgTypeUnknown	1000	Unknown type, as default

Message settings such as push, anti-spam, etc. similar to IM message setting.

Receive System Notification

Register/cancel the event of receiving system messages. Registration needs to be completed before logging in. To ensure consistent logic of the entire program, APP needs to perform operations correspondingly with different types of system notifications.

• API prototype

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

• Parameter Description

Parameter	Description
cb	Notification callback
json_extension	Extension field. Reserved
user_data	APP's custom user data, which SDK is only responsible for passing back to the callback function cb(without any processing)

• Example

//Receive callback for system notifications
void my_nim_sysmsg_receive_cb_func(const char *content, const char *json_extension, const void *user_data)
{
	//Content is parsed into SysMessage
    Json::Value values;
	Json::Reader reader;
	if (reader.parse(content, values) && values.isObject())
	{
		NIMResCode rescode_ = (NIMResCode)values[kNIMSysMsgKeyLocalRescode].asUInt();
		NIMMessageFeature feature_ = (NIMMessageFeature)values[kNIMSysMsgKeyLocalFeature].asUInt();
		int total_unread_count_ = values[kNIMSysMsgKeyLocalUnreadCount].asUInt();

		//Parse notification content into NIMSysMessageContent defined content
		Json::Value message = values[kNIMSysMsgKeyLocalContent];
		ParseSysMessageContent(message);
	}
}
//Monitor event
nim_sysmsg_reg_sysmsg_cb(0，my_nim_sysmsg_receive_cb_func,0);

//Cancel monitoring
nim_sysmsg_reg_sysmsg_cb(0,0,0);

Send Custom 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 sent from client is defined by the developer (kNIMSysMsgKeyAttach), and SDK is only responsible for sending and receiving the notification via online or offline channel, including point-to-point notification and team notification, but without doing 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, etc.

In addition, the content of custom system notification (SysMessage also supports property settings as follows:

• Whether custom notification is saved offline
• Push notification copy of custom system notification
• Third-party custom push attribute
• Determine if push is needed
• Whether counting is needed for push message
• Whether a nickname is needed for push message

Note: SDK is not responsible for the persistence of custom notifications, parsing and persisting of which should be done by APP as needed according to its own business logic.

• API prototype

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

• Parameter Description

Parameter	Description
json_msg	Message content, see SysMessage for detail.
json_extension	Extension field. Reserved

• Example

//Take the test account test1 as an example;
Json::FastWriter fw;

//Create notification content
Json::Value message;
message[kNIMSysMsgKeyToAccount] = "test1";
message[kNIMSysMsgKeyType] = type;
message[kNIMSysMsgKeyLocalClientMsgId] = "Unique uuid of a message";//Generated by developers
values[kNIMSysMsgKeyTime] = 1520423612222;//Current time UNIX timestamp 13-byte (ms)

//Message settings, as required
message[kNIMSysMsgKeyPushNeedBadge] = 1;
message[kNIMSysMsgKeyPushEnable] = 1;
message[kNIMSysMsgKeyPushNeedPrefix] = 1;
message[kNIMSysMsgKeyCustomSaveFlag] = 1;
message[kNIMSysMsgKeyCustomApnsText] = "This is a push notification message";//Content of push message
message[kNIMSysMsgKeyAntiSpamEnable] = 1;
message[kNIMSysMsgKeyAntiSpamContent] = "{\"type\":0,\"data\":\"sss\"}";//Refer to IM anti-spam settings

//Available to create attachment content
Json::Value attchment;
attchment["content"] = "This is attachment content";
attchment["id"] = 2;
message[kNIMSysMsgKeyAttach] = fw.write(attchment);

//You can add payload information push
Json::Value payload;
payload["Content"] = "This is payload information";
message[kNIMSysMsgKeyPushPayload] = fw.write(payload);

char* msg = fw.write(message);

....

//Send message
nim_sysmsg_send_custom_notification(msg,0);

Result Notification of Sending Custom System Notification

Result notification of sending custom notification message.

• API prototype

void nim_sysmsg_reg_custom_notification_ack_cb(const char *json_extension, nim_custom_sysmsg_ack_cb_func cb, const void *user_data);

• Parameter Description

Parameter	Description
cb	Notification callback
json_extension	Extension field. Reserved
user_data	APP's custom user data, which SDK is only responsible for passing back to the callback function cb(without any processing)

• Example

void my_nim_custom_sysmsg_ack_cb_func(const char *result, const void *user_data)
{
	// parse result
	Json::Value values;
	Json::Reader reader;
	if (reader.parse(result, values) && values.isObject())
	{
		NIMResCode rescode = (NIMResCode)values[kNIMSendAckKeyRescode].asUInt();
		char* msg_id = values[kNIMSendAckKeyMsgId].asString();
		char* talk_id = values[kNIMSendAckKeyTalkId].asString();
		int64_t msg_timetag = values[kNIMSendAckKeyTimetag].asInt64();
		...
	}
	...
}
//Monitor event
nim_sysmsg_reg_custom_notification_ack_cb(0,my_nim_custom_sysmsg_ack_cb_func,0);

//Cancel monitoring
nim_sysmsg_reg_custom_notification_ack_cb(0,0,0);

Notification Message Management

SDK provides interfaces for querying message history, unread messages, setting as read, deleting notifications, etc.

Query System Notification

Query local system messages (search in reverse order of time, with results sorted in reverse order).

nim_sysmsg_query_cb_funcParameter description

Type	Parameter	Description
int	count	Total number of messages
int	unread_count	Total number of unread notification messages
string	result	Notification message collection, see SysMessage for details).
user_data	APP's custom user data, which SDK is only responsible for passing back to the callback function cb(without any processing)

• API prototype

//Query the result callback
void nim_sysmsg_query_msg_async(int limit_count, int64_t last_time, const char *json_extension, nim_sysmsg_query_cb_func cb, const void *user_data);

• Parameter Description

Parameter	Description
limit_count	Number of sessions for one query, 20 is the recommended value
last_time	The timestamp of the last message of the last query (searched in reverse order of time, meaning it is the smallest timestamp), fill in 0 for initial query
cb	Operation result callback
json_extension	Extension field. Reserved
user_data	APP's custom user data, which SDK is only responsible for passing back to the callback function cb(without any processing)

• Example

void my_nim_sysmsg_query_cb_func(int count, const char *result, const char *json_extension, const void *user_data)
{
	// parse result
    Json::Value values;
	Json::Reader reader;
	if (reader.parse(sysmsgs_json, values) && values.isObject())
	{
		uint unread = values[kNIMSysMsglogQueryKeyUnreadCount].asUInt();
		Json::Value content = values[kNIMSysMsglogQueryKeyContent];
		int len = content.size();
		for (int i = 0; i < len; i++)
		{
        	//Parse into NIMSysMessageContent defined data
			Json::Value message = content[i];
            ParseSysMessageContent(message);
            ...
		}
        ...
	}
}
//Initial query
nim_sysmsg_query_msg_async(20,0,0,my_nim_sysmsg_query_cb_func,0);

//Assuming the last message timestamp of the initial query is '1520423612222’
nim_sysmsg_query_msg_async(20,1520423612222,0,my_nim_sysmsg_query_cb_func,0);

Query Unread Count

• API prototype

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

• Parameter Description

Parameter	Description
cb	Operation result callback
json_extension	Extension field. Reserved
user_data	APP's custom user data, which SDK is only responsible for passing back to the callback function cb(without any processing)

• Example

void my_nim_sysmsg_res_cb_func(int res_code, int unread_count, const char *json_extension, const void *user_data)
{
	...
}
// Query unread count
nim_sysmsg_query_unread_count(0,my_nim_sysmsg_res_cb_func,0);

Set Message Status

Message status settings include Pass, Decline, Read, Invalid, etc.

NIMSysMsgStatusEnumeration description

Enumeration	Value	Description
kNIMSysMsgStatusNone	0	Default, unread
kNIMSysMsgStatusPass	1	Received, pass
kNIMSysMsgStatusDecline	2	Received, decline
kNIMSysMsgStatusRead	3	Received, read
kNIMSysMsgStatusDeleted	4	Deleted
kNIMSysMsgStatusInvalid	5	Invalid

• API prototype

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

• Parameter Description

Parameter	Description
msg_id	Message id
status	Message status, see NIMSysMsgStatus for details.
cb	Operation result callback
json_extension	Extension field. Reserved
user_data	APP's custom user data, which SDK is only responsible for passing back to the callback function cb(without any processing)

• Example

void my_nim_sysmsg_res_ex_cb_func(int res_code, int64_t msg_id, int unread_count, const char *json_extension, const void *user_data)
{
    if (res_code == 200)//Successful
    {
		...
    }
}
// Set message status:
int64_t msgId = "213213111";
nim_sysmsg_set_status_async(msgId,kNIMSysMsgStatusPass,0,my_nim_sysmsg_res_ex_cb_func,0);

Set Message Status in Bulk by Message Type

• API prototype

void nim_sysmsg_set_logs_status_by_type_async(enum NIMSysMsgType type, enum NIMSysMsgStatus status, const char *json_extension, nim_sysmsg_res_cb_func cb, const void *user_data);

• Parameter Description

Parameter	Description
type	Message type, see NIMSysMsgType for details.
status	Message status, see NIMSysMsgStatus for details.
cb	Operation result callback
json_extension	Extension field. Reserved
user_data	APP's custom user data, which SDK is only responsible for passing back to the callback function cb(without any processing)

• Example

void my_nim_sysmsg_res_cb_func(int res_code, int unread_count, const char *json_extension, const void *user_data)
{
	if (res_code == 200)//Successful
    {
		...
    }
}
//Set message status by type
nnim_sysmsg_set_logs_status_by_type_async(kNIMSysMsgTypeTeamApply, kNIMSysMsgStatusPass, 0,my_nim_sysmsg_res_cb_func，0);

Set all read

• API prototype

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

• Parameter Description

Parameter	Description
cb	Operation result callback
json_extension	Extension field. Reserved
user_data	APP's custom user data, the SDK is only responsible for passing back to the callback function (without any processing)

• Example

void my_nim_sysmsg_res_cb_func(int res_code, int unread_count, const char *json_extension, const void *user_data)
{
	...
}
//Set all read
nim_sysmsg_read_all_async(0,my_nim_sysmsg_res_cb_func,0);

Delete a single notification

• API prototype

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

• Parameter Description

Parameter	Description
msg_id	Message id
cb	Operation result callback
json_extension	Extension field. Reserved
user_data	APP's custom user data, which SDK is only responsible for passing back to the callback function cb(without any processing)

• Example

void my_nim_sysmsg_res_ex_cb_func(int res_code, int64_t msg_id, int unread_count, const char *json_extension, const void *user_data)
{
    if (res_code == 200)//Successful
    {
		...
    }
}
// Delete messages
int64_t msgId = 213213111;
nim_sysmsg_delete_async(msgid,0, my_nim_sysmsg_res_ex_cb_func,0);

Delete messages by type in batches

• API prototype

void nim_sysmsg_delete_logs_by_type_async(enum NIMSysMsgType type, const char *json_extension, nim_sysmsg_res_cb_func cb, const void *user_data);

• Parameter Description

Parameter	Description
type	Message type, see NIMSysMsgType for details
cb	Operation result callback
json_extension	Extension field. Reserved
user_data	APP's custom user data, which SDK is only responsible for passing back to the callback function cb(without any processing)

• Example

void my_nim_sysmsg_res_cb_func(int res_code, int unread_count, const char *json_extension, const void *user_data)
{
	...
}
//Delete all messages of the type kNIMSysMsgTypeTeamApply
nim_sysmsg_delete_logs_by_type_async(kNIMSysMsgTypeTeamApply,0, my_nim_sysmsg_res_cb_func,0);