Custom system notification

Update time: 2023/04/17 11: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

POST 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:

ParameterTypeRequiredDescription
fromStringYes Sender accid, user account, at most 32 characters, unique in your app
msgtypeintYes 0: p2p custom notification, 1: group custom notification. Return 414 for other values.
toStringYes 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
attachStringYes The specific content of a custom system notification, the concatenated string in JSON (recommended). The maximum length of the content is 4096 characters.
pushcontentString Body of a push notification | Up to 500 characters. For more information about push notifications, see Configure parameters for the push notification service.
payloadStringNo 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.
soundStringNo 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.
saveintNo 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 StringNo 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

curl -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

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

Example error response

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

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

  • Apps can call the API by 120 times per minute. - If the limit is exceeded, an error will be thrown (status code: 416), and requests sent from the client will be blocked for 1 minute before the app can call the API again.
  • You can send custom system notifications to a maximum of 5,000 recipients. If unregistered accounts are included in the recipients, the sender gets notified.

URL

POST https://api.netease.im/nimserver/msg/sendBatchAttachMsg.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:

ParameterTypeRequiredDescription
fromAccid StringYes Unique IM account (accid) of the sender. Up to 32 characters are allowed.
toAccids StringYesList of recipients In JSONArray, for example, ["aaa", "bbb"]. If parsing data fails, a 414 error is thrown. Up to 500 recipients.
attachStringYes The content of a custom notification in String, Up to 4,096 characters long.
pushcontentString Body of a push notification | Up to 500 characters. For more information about push notifications, see Configure parameters for the push notification service.
payloadStringNo The payload of a push notification must be in JSON format and cannot exceed 2,000 characters. For more information about push notifications, see Configure parameters for the push notification service.
soundStringNo 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.
saveintNo 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 StringNo Options for sending a custom system notification in JSON format. For example, you can specify whether custom system notifications are counted as unread
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.
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)

Response parameters

Parameter Type Description
unregister String Unregistered users included in the toAccids list. Example: ["123123","111422"]. If no unregistered users are included, no data for this parameter is returned.

Example

cURL request example

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'fromAccid=zhangsan&toAccids=["aaa","bbb"]&attach={"myattach":"test"}' 'https://api.netease.im/nimserver/msg/sendBatchAttachMsg.action'

Example success response

HTTP response in JSON

"Content-Type": "application/json; charset=utf-8"
{
  "code": 200,
  "unregister": ["123123","111422"] 
}

Example error response

"Content-Type": "application/json; charset=utf-8"
{
    "code": 414
    "desc": "more than 500 accids!"  // The number of recipients exceeds 500.
}

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 -
403 Possible reasons for a failed request:
  • Authentication failed
  • The message cannot be recalled.
  • </ ul>
Handle the error based on the specific message.
414 Parameter error Check the format and restrictions of arguments based on the error message.
500 Internal Server Error -
Was this page helpful?
Yes
No
  • Send a custom system notification
  • Rate limit
  • URL
  • Request parameters
  • Example
  • cURL request example
  • Example success response
  • Example error response
  • Status code
  • Send multiple P2P custom system notifications
  • Rate limit
  • URL
  • Request parameters
  • Response parameters
  • Example
  • cURL request example
  • Example success response
  • Example error response
  • Status code