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:
|
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.
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
httpPOST 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:
Parameter | Type | Required | Description |
---|---|---|---|
fromAccid | String | Yes | Unique IM account (accid) of the sender. Up to 32 characters are allowed. |
toAccids | String | Yes | List of recipients In JSONArray, for example, ["aaa", "bbb"]. If parsing data fails, a 414 error is thrown. Up to 500 recipients. |
attach | String | Yes | The content of a custom notification in String, Up to 4,096 characters long. |
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 2,000 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 | 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 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:
|
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
curlcurl -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
json"Content-Type": "application/json; charset=utf-8"
{
"code": 200,
"unregister": ["123123","111422"]
}
Example error response
json"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:
|
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 | - |