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.
SysMessage
Parameter description
Type | Parameter | Description |
---|---|---|
NIMResCode | rescode_ | Notification error codes, see NIMResCode for 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) |
SysMessageSetting
Description 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_ |
NIMSysMsgType
Description 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).
QueryMsgCallback
Parameter 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.
NIMSysMsgStatus
Enumeration 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
{
...
}
});