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

httpPOST 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

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&body=abc' 'https://api.netease.im/nimserver/msg/broadcastMsg.action'

Example success response

HTTP response in JSON

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

json"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: 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.
416	Too many requests	Lower the number of requests within a period of time.
500	Internal Server Error	-

Delete a broadcast message

URL

httpPOST  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)

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

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