Custom system notification - Instant Messaging

Documentation

Instant Messaging

Server API

Custom system notification

Update time: 2023/04/17 03:18:21

You can send a custom system notification by calling the corresponding server API.

This document describes how to send one or more custom system notifications by calling server APIs.

Send a custom system notification

Different from regular messages, custom system notifications are used for business logic. Two custom system notification types are supported: peer-to-peer and group. The types are identified by the msgType parameter.

Typical scenario: If a user sends a friend request to another user, you can add custom content to the request (recommended in JSON format).

Rate limit

The API can be called by 100 times per second for each app. If app users call the API exceeding the limit, the app will be blocked for 10 seconds before the API become available again.

URL

httpPOST https://api.netease.im/nimserver/msg/sendAttachMsg.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

Request parameters

For information about how to set the header in a POST request, see API Call methods.
The settings of the body in a POST request:

Parameter	Type	Required	Description
from	String	Yes	Sender accid, user account, at most 32 characters, unique in your app
msgtype	int	Yes	0: p2p custom notification, 1: group custom notification. Return 414 for other values.
to	String	Yes	If msgtype=0, you must fill in the CommsEase IM account (accid) of the user receiving the system notification. If msgtype=1, you must fill in the ID (tid) of the group receiving the system notification, with a maximum of 32 characters
attach	String	Yes	The specific content of a custom system notification, the concatenated string in JSON (recommended). The maximum length of the content is 4096 characters.
pushcontent	String	否	Body of a push notification \| Up to 500 characters. For more information about push notifications, see Configure parameters for the push notification service.
payload	String	No	The payload of a push notification must be in JSON format and cannot exceed 2000 characters. For more information about push notifications, see Configure parameters for the push notification service.
sound	String	No	If a specific push notification is used, this property indicates the name of a local sound file. the length can not exceed 30 characters. If unspecified, the default sound will be used.
save	int	No	Only 1 or 2 can be used. 1: only online participants can receive system notifications. 2: system notifications are saved for offline participants. If other values are specified, an error will be thrown (status code: 414). By default, system notifications are saved for offline users.
option	String	No	Options for sending a system notification in JSON. For example, you can specify whether the custom system notification is counted as unread. If the option field is unspecified, the default value is applied. option example: {"badge": false, "needPushNick": false, "route": false} Fields: badge: whether the system notification is counted as unread. The default value is true needPushNick: Whether the push payload contains the nickname. The default value is false. Note that the default value is different from the needsPushNick parameter in sendMsg.action. route: Whether the system notification is synced with the app server configured in the CommsEase console. The default value is true (Data sync must be enabled)
isForcePush	boolean	No	Whether the custom system notification is force pushed. The default value is false.
forcePushContent	String	No	The content of a custom system notification to be force pushed, up to 500 characters long.
forcePushAll	boolean	No	Whether a custom system notification is force pushed to all valid group members except the sender. The default value is false.
forcePushList	String	No	The list of group members to whom a custom system notifications is force pushed. The list is in JSONArray, example: ["accid1", "accid2"], up to 100 users.
env	String	No	The environment name for data sync, consistent with the environment name specified in the CommsEase console for data sync as shown in the figure below. A maximum of 32 characters are allowed. ![Custom environment.png](https://yx-web-nosdn.netease.im/common/67dfaa431a321abfb77e5f238da47b62/Custom environment.png)

Example

cURL request example

curlcurl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'from=zhangsan&msgtype=0&to=lisi&attach={"myattach":"test"}' 'https://api.netease.im/nimserver/msg/sendAttachMsg.action'

Example success response

HTTP response in JSON

json"Content-Type": "application/json; charset=utf-8"
{
  "code":200
}

Example error response

json"Content-Type": "application/json; charset=utf-8"
{
    "code":414
    "desc":"check msgType"  // msgType is not "0” or "1"
}

Status code

The following status codes are related to responses of this API. For more status codes, see Status codes。

Status code	Description	Recommendation
200	Success	-
414	Parameter error	Check the format and restrictions of arguments based on the error message.
403	Permission verification failed, access forbidden	-
500	Internal Server Error	-

Send multiple P2P custom system notifications

System notifications are different from ordinary messages. After receiving system notifications, the SDK sends them to the upper layer of the application for processing. Clients do not need to display them.