System Notification

Update time: 2021/09/25 14:02:50

In addition to the message channel, SDK also provides a system notification channel for the 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 rescode_ Notification error codes, see NIMResCodefor details
NIMMessageFeature feature_ Notification attributes, with differences between offline, multi-terminal synchronization, roaming notifications, etc., see NIMMessageFeature for details.
int total_unread_count_ Total number of unread notifications
int64_t timetag_ Notification timestamp (in milliseconds), optional
NIMSysMsgType type_ Type of notification, such as team joining application, team joining invitation, add friend, etc., see NIMSysMsgType for details.
string receiver_accid_ Receiver id, user id if receiver is a user, or team id if receiver is a team, required
string sender_accid_ Sender id, optional in cases such as sending a custom notification
string content_ Notification P.S., to be completed as needed
string attach_ Attachment, to be completed as needed, similar to the attachment content of ordinary IM messages, view the message sent.
int64_t id_ Server message id (custom notification, value filled in must be 0), not required for the sender
NIMSysMsgStatus status_ Locally defined system message status, see NIMSysMsgStatus, not required for the sender
SysMessageSetting msg_setting_ Message attribute settings, see SysMessageSetting for details.
string client_msg_id_ Notification ID (client)

SysMessageSettingDescription of notification type

Type Parameter Description
int need_offline_ (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 push_content_ Push notification copy of custom system notification, no push if left blank
int need_push_ (Optional) Whether push is needed, 0: not needed, 1: needed, set to 1 by default, should be used withpush_content_
int push_need_badge_ (Optional) Whether message count (corner mark) is needed, 0: not needed, 1: needed, set to 1 by default, should be used withpush_content_
int push_need_prefix_ (Optional) Whether nickname push is needed, 0: not needed, 1: needed, set to 0 by default, should be used withneed_push_
Json::Value push_payload_ (Optional) Third-party custom push load content, must be an unformatted string that can be parsed as json, with a length of 2048
bool anti_spam_enable_ (Optional) Whether to enable anti-spam of YiDun, set to false by default
string anti_spam_content_ (Optional) Developer-defined anti-spam field, with a length limit of 5000 characters, should be used withanti_spam_enable_

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 Unfriend
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
static void RegSysmsgCb(const ReceiveSysmsgCallback& cb, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
cb Notification callback
json_extension Extension field. Reserved
  • Example
//Monitor event
nim::SystemMsg::RegSysmsgCb([&](const nim::SysMessage& ret){
	...
});

//Cancel monitoring
nim::SystemMsg::RegSysmsgCb(nullptr);

Create Custom System Notification

Makes it convenient for users to customize notification contents.

  • API prototype
static std::string CreateCustomNotificationMsg(const std::string& receiver_id, const NIMSysMsgType type, const std::string& client_msg_id, const std::string& content, const SysMessageSetting& msg_setting, int64_t timetag = 0);
  • Parameter Description
Parameter Description
receiver_id Receiver ID
type Notification type, see NIMSysMsgType for details
client_msg_id Unique id of the message
content Notification content
msg_setting Message setting, see SysMessageSetting for details
timetag Current timestamp (in milliseconds)

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 (Attachment), 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, custom system notification content SysMessage also provides the following attribute settings SysMessageSetting:

  • Whether custom notification is saved offline
  • Push notification copy of custom system notification
  • Third-party custom push attribute
  • Determine whether 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
static void SendCustomNotificationMsg(const std::string& json_msg);
  • Parameter Description
Parameter Description
json_msg Message content, see SysMessage for details
  • Example
//Take the test account test1 as an example;
Json::FastWriter writer;
int64_t timetag = 1520423612222;//13-bit UNIX timestamp of the current time (in milliseconds)

nim::SysMessageSetting setting;
setting.need_push_ = true;
setting.need_offline_ = true;//Offline save
setting.push_need_badge_ = true;//Push and count
setting.push_need_prefix_ = true;//Push notification has a prefix, example: mmm: notification content
setting.push_content_ = "This is a push notification";//push message content
//You can add payload information push
Json::Value payload;
payload["Content"] = "This is payload information";
setting.push_payload_ = writer.write(payload);


Json::Value values;
values["content"] = "This is attachment content";
values["id"] = 2;

//Create notification content
std::string msg = nim::SystemMsg::CreateCustomNotificationMsg("test1",kNIMSysMsgTypeCustomP2PMsg,"Develop and generate unique uuid",writer.write(values),setting,timetag);

....

//Send message
nim::SystemMsg::SendCustomNotificationMsg(msg);

Result notification of sending custom system notification

Result notification of sending custom notification message.

  • API prototype
static void RegSendCustomSysmsgCb(const SendCustomSysmsgCallback& cb, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
cb Notification callback
json_extension Extension field. Reserved
  • Example
//Monitor event
nim::SystemMsg::RegSendCustomSysmsgCb([&](const nim::SendMessageArc& ret)
{
	...
});

//Cancel monitoring
nim::SystemMsg::RegSendCustomSysmsgCb(nullptr);

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

QueryMsgCallbackParameter description

Type Parameter Description
int count Total number of messages
int unread_count Total number of unread notification messages
std::list< nim::SysMessage > result Notification message collection, see SysMessage for details.
  • API prototype
static bool QueryMsgAsync(int limit_count, int64_t last_time, const QueryMsgCallback& cb, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
limit 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
  • Example
//Initial query
nim::SystemMsg::QueryMsgAsync(20,0,[&](int count, int unread, const std::list<nim::SysMessage>& result)
{
	...
});

//Assuming the last message timestamp of the initial query is '1520423612222’
nim::SystemMsg::QueryMsgAsync(20,1520423612222,[&](int count, int unread, const std::list<nim::SysMessage>& result)
{
	...
});

Query unread count

  • API prototype
static void QueryUnreadCount(const QuerySysmsgUnreadCallback& cb, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
cb Operation result callback
json_extension Extension field. Reserved
  • Example
// Query unread count
nim::SystemMsg::QueryUnreadCount([&](NIMResCode ret, int count)
{
	...
});

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
static bool SetStatusAsync(int64_t msg_id, nim::NIMSysMsgStatus status, const SetStatusCallback& cb, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
msg_id Message id
status Message status, see NIMSysMsgStatus for details
cb Operation result callback
json_extension Extension field. Reserved
  • Example
// Set message status:
int64_t msgId = 213213111;
nim::SystemMsg::SetStatusAsync(msgId,kNIMSysMsgStatusPass,[&](NIMResCode ret, int64_t id, int count)
{
	if (ret == 200)//success
    {
		...
    }
});

Set message status in batches by message type

  • API prototype
 static void SetStatusByTypeAsync(NIMSysMsgType type, NIMSysMsgStatus status, const BatchSetCallback& cb, const std::string& json_extension = "");
  • 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
  • Example
//Set message status by type
nim::SystemMsg::SetStatusByTypeAsync(kNIMSysMsgTypeTeamApply, kNIMSysMsgStatusPass, [&](NIMResCode ret, int count)
{
    if (code == 200)//success
    {
		...
    }
});

Set all read

  • API prototype
static void ReadAllAsync(const ReadAllCallback& cb, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
cb Operation result callback
json_extension Extension field. Reserved
  • Example
//Set all read
nim::SystemMsg::ReadAllAsync([&](NIMResCode ret, int unread_count)
{
    ...
});

Delete a single notification

  • API prototype
static bool DeleteAsync(int64_t msg_id, const DeleteCallback& cb, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
msg_id Message id
cb Operation result callback
json_extension Extension field. Reserved
  • Example
// Delete messages
int64_t msgId = 213213111;
nim::SystemMsg::DeleteAsync(msgid, [&](NIMResCode ret, int64_t id, int count)
{
    ...
});

Delete messages by type in batches

  • API prototype
static void DeleteByTypeAsync(NIMSysMsgType type, const BatchSetCallback& cb, const std::string& json_extension = "");
  • Parameter Description
Parameter Description
type Message type, see NIMSysMsgType for details
cb Operation result callback
json_extension Extension field. Reserved
  • Example
//Delete all messages of the type kNIMSysMsgTypeTeamApply
nim::SystemMsg::DeleteByTypeAsync(kNIMSysMsgTypeTeamApply, [&](NIMResCode ret, int count)
{
    if (ret == 200)//success
    {
		...
    }
});
Was this page helpful?
Yes
No
  • Receive System Notification
  • Create Custom System Notification
  • Send custom system notification
  • Result notification of sending custom system notification
  • Notification message management
  • Query system notification
  • Query unread count
  • Set message status
  • Set message status in batches by message type
  • Set all read
  • Delete a single notification
  • Delete messages by type in batches