Custom System Notifications - Instant Messaging

Documentation

Instant Messaging

Guides

System Notification

Custom System Notifications

Update time: 2023/03/23 17:45:08

The NIM SDK supports custom system notifications, helping you implement diverse business scenarios.

This document introduces the technical principle, specific implementation process and typical application scenarios of custom system notifications.

How it works

Custom system notification can be delivered from clients or the app server. The SDK only transparently transmits custom system notifications, and does not parse and store them. The content of a notification can be customized.

You can send custom notifications for some events based on your business logic to implement various types of business scenarios. For example, the "typing" indicator of a user in a one-on-one chat.

Implementation

C++

Use the callback template (ReceiveSysmsgCallback) and call the RegSysmsgCb method to listen to the system events.

Use the callback template（SendCustomSysmsgCallback）and register the RegSendCustomSysmsgCb callback for sending custom system notifications.

Sample code:

// Listen to system events
SystemMsg::RegSysmsgCb([](const SysMessage& msg) {
	// Handle the message.
});

// Listen to custom system events
SystemMsg::RegSendCustomSysmsgCb([](const SendMessageArc& arc) {
    // process arc
});

Call the nim_sysmsg_reg_sysmsg_cb method to listen to the system events.
Register the nim_sysmsg_reg_custom_notification_ack_cb callback to listen to custom system events.

Sample code:

// Listen to system events
static void CallbackSysmsg(const char* result, const char* json_extension, const void* callback) {
    
}
nim_sysmsg_reg_sysmsg_cb("", &CallbackSysmsg, NULL);

// Listen to custom system events
static void CallbackSendCustomSysmsg(const char* result, const void* callback) {
    
}
nim_sysmsg_reg_custom_notification_ack_cb("", &CallbackSendCustomSysmsg, NULL);

Construct a custom system notification

Implementation in C++

Create a custom system notification by calling the CreateCustomNotificationMsg method.

Parameters:

Parameter	Description
timetag	The timestamp when a system notification is sent
Type	Type of events for which built-in system notifications are sent. For more information, see `NIMSysMsgType`
content	The content of a system notification.
receiver_id	The ID of a recipient.
client_msg_id	Client ID of a notification.
msg_setting	The configuration of a system notification, such as whether the system notification are delivered as push notification, counted as unread, whether the sytem notification are delivered when the target user is offline. For more information, see `SysMessageSetting`

** Sample code:**

std::string sysmsg = SystemMsg::CreateCustomNotificationMsg("receiver_id", kNIMSysMsgTypeCustomTeamMsg, "client_msg_id", "content", SysMessageSetting());

Send a custom system notification

C++

Send a custom system notification by calling the SendCustomNotificationMsg method. Sample code:

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

	nim::SysMessage msg;
	msg.receiver_accid_ = ;	//The ID of a recipient
	msg.sender_accid_ = ; 	//The ID of a sender
	msg.client_msg_id_ = QString::GetGUID();	//Client ID of a message
	msg.attach_ = writer.write(json);			//The attachment of a notification
	msg.type_ = nim::kNIMSysMsgTypeCustomP2PMsg; // Notification type

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

Send a custom system notification by calling the nim_sysmsg_send_custom_notification method. Sample code:

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

void foo()
{
	//json_msg：For the definition of key, see the system message field in nim_sysmsg_def.h
	Json::Value json_msg;
	json_msg[kNIMSysMsgKeyToAccount] = ; //The ID of a recipient
	json_msg[kNIMSysMsgKeyFromAccount] = ; //The ID of a sender
	json_msg[kNIMSysMsgKeyLocalClientMsgId] = Client ID of a message 
	json_msg[kNIMSysMsgKeyTime] = ; // Timestamp
	json_msg[kNIMSysMsgKeyAttach] = ; //The attachment of a notification
	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);
}

By default, up to 100 calls per second are allowed. - To increase the limit, contact the sales manager over the Whatsapp on the CommsEase website.

Trigger the callback to receive the custom system notification

Use cases

The "typing" indicator of a user in a one-on-one chat. Sample code:

C++

SystemMsg::RegSysmsgCb([](const SysMessage& msg) {
	if (msg.type_ == kNIMSysMsgTypeCustomP2PMsg) {
		// Custom one-on-one messages
		Json::Value value;
		Json::Reader reader;
		if (reader.parse(msg.attach_, value) && value.isObject()) {
			auto msg_type = value["msg_type"].asString();
			if (msg_type == "typing") {
				std::cout << "Received the notification that the user is typing" << std::endl;
				// process typing notification
				// ...
				return;
			}
			// ...
		}
	}
	// ...
});

void SendTypingNotification(){
	Json::Value json;
	Json::FastWriter writer;
	json["msg_type"] = "typing";

	nim::SysMessage msg;
	msg.receiver_accid_ = ;	//The ID of a recipient
	msg.sender_accid_ = ; 	//The ID of a sender
	msg.client_msg_id_ = QString::GetGUID();	//Client ID of a message
	msg.attach_ = writer.write(json);			//The attachment of a notification
	msg.type_ = nim::kNIMSysMsgTypeCustomP2PMsg; // Notification type

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

static void CallbackSysmsg(const char* result, const char* json_extension, const void* callback) {
    // 
}
nim_sysmsg_reg_sysmsg_cb("", &CallbackSysmsg, NULL);

void SendTypingEvent() {
	//json_msg：For the definition of key, see the system message field in nim_sysmsg_def.h
	Json::Value json_msg;
	Json::Value attach;
	attach["msg_type"] = "typing";
	json_msg[kNIMSysMsgKeyToAccount] = ; //The ID of a recipient
	json_msg[kNIMSysMsgKeyFromAccount] = ; //The ID of a sender
	json_msg[kNIMSysMsgKeyLocalClientMsgId] = Client ID of a message 
	json_msg[kNIMSysMsgKeyTime] = ; // Timestamp
	json_msg[kNIMSysMsgKeyAttach] = GetJsonStringWithNoStyled(attach); //The attachment of a notification
	json_msg[kNIMSysMsgKeyType] = kNIMSysMsgTypeCustomP2PMsg; // 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);
}

API reference

C++

API	Description
`RegSysmsgCb`	Listener to the event of receiving system notifications.
`RegSendCustomSysmsgCb`	Listen to the callback for sending a custom system notification.
`CreateCustomNotificationMsg`	Construct a custom system notification.
`SendCustomNotificationMsg`	Send a custom system notification.

API	Description
`nim_sysmsg_reg_sysmsg_cb`	Listener to the event of receiving system notifications.
`nim_sysmsg_reg_custom_notification_ack_cb`	Listen to the callback for sending a custom system notification.
`nim_sysmsg_send_custom_notification`	Send a custom system notification.

Was this page helpful?

Yes

How it works
Implementation
Use cases
API reference