Send Broadcast Messages
Update time: 2023/05/05 14:34:58
Broadcast messages can be sent to all users within the app. This feature is suitable for business scenarios where all users need to be notified, such as sending internal announcements within an organization to all employees.
Broadcast messages can also be deleted if necessary.
You can also query the history of broadcast messages. For more information, see Query Broadcast Messages.
Send a broadcast message
To receive broadcast messages on the client side, you must register the corresponding listener/callback function on the client side. Otherwise, the client cannot receive broadcast messages. For more information, see the SDK documentation for each platform. For example, to receive broadcast messages on Android apps, see Send broadcast messages.
- Broadcast messages cannot be sent over third-party push notification services, such as APNs, Xiaomi Push, and Huawei Push Kit).
- Broadcast messages can be stored for offline accounts. You can set a custom validity period for storing broadcast messages. Up to 100 recent broadcast messages can be stored for offline devices.
Rate limit
- You must activate broadcast messages separately. Before building related features, make sure you have contacted the sales manager and activated the service. You can contact the sales manager using Whatsapp on the CommsEasewebsite.
- NIM SDK v4.3.0 and later. SDKs earlier than v4.3.0 do not support broadcast messages.
- The rate limit of this API: 10 times/min. If the limit is exceeded, an error will be thrown (status code: 416), and requests sent from the app will be blocked for 1 minute for before the app can call the API again.
URL
POST https://api.netease.im/nimserver/msg/broadcastMsg.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 |
---|---|---|---|
body | String | Yes | The body of a broadcast message can contain up to 4096 characters. |
from | String | No | Unique IM account (accid) of the sender. Up to 32 characters are allowed. |
isOffline | boolean | No | Whether broadcast messages are stored for offline devices. The default value is false |
ttl | int | No | Validity period for stored broadcast messages in hours. The default value is 7 days |
targetOs | Array | No | Target client. All types of clients are valid by default in JSONArray: ["ios", "aos", "pc", "web", "mac"]. |
Response parameters
Parameter | Type | Description |
---|---|---|
msg | JSON | Broadcast message. See the following table for specific information. |
Member properties of the msg schema:
Parameter | Type | Description |
---|---|---|
broadcastid | Long | ID of the broadcast message, unique within the app |
from | String | CommsEase IM account of the sender |
body | String | Body of the broadcast message |
targetOs | JSONArray | Target clients, for example, ["ios","aos","pc","web","mac"] |
isOffline | boolean | Whether the broadcast message is stored for offline devices |
createTime | Long | The time when the broadcast message was created. |
expireTime | Long | The expiration time of the broadcast message. |
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&body=abc' 'https://api.netease.im/nimserver/msg/broadcastMsg.action'
Example success response
HTTP response in JSON
"Content-Type": "application/json; charset=utf-8"
{
"code": 200,
"msg": {
"expireTime": 1505502793520,
"body": "abc",
"createTime": 1505466793520,
"isOffline": true,
"broadcastId": 48174937359009,
"targetOs": [
"ios",
"pc",
"aos"
]
}
}
Example error response
"Content-Type": "application/json; charset=utf-8"
{
"code":414
"desc":"ttl exceeds" // The value of the ttl parameter exceeds the upper limit.
}
Status code
The following status codes are related to responses of this API. For more status codes, see Status codes.
Status code | Description | Recommendation |
---|---|---|
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. |
416 | Too many requests | Lower the number of requests within a period of time. |
500 | Internal Server Error | - |
Delete a broadcast message
URL
POST https://api.netease.im/nimserver/history/delBroadcastMsgById.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 |
---|---|---|---|
broadcastId | Long | Yes | Unique ID of a broadcast message |
Example
Example request (cURL)
curl -X POST -H "appkey: fe416***d2547" -H "nonce: 12345" -H "curtime: 1459154905" -H "checksum: 8d3ef***5fc9d3" -H "Content-Type: application/x-www-form-urlencoded" -d 'broadcastId=123456' "https://api.netease.im/nimserver/history/delBroadcastMsgById.action"
Response
"Content-Type": "application/json; charset=utf-8"
{
"code": 200
}
Status codes
The status code is returned in the response body. For more information, see Status codes.