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:

ParameterTypeRequiredDescription
body String Yes The body of a broadcast message can contain up to 4096 characters.
from StringNo Unique IM account (accid) of the sender. Up to 32 characters are allowed.
isOffline booleanNo Whether broadcast messages are stored for offline devices. The default value is false
ttl intNo Validity period for stored broadcast messages in hours. The default value is 7 days
targetOs ArrayNo 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:
  • 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

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:
ParameterTypeRequiredDescription
broadcastId LongYesUnique 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.

Was this page helpful?
Yes
No
  • Send a broadcast message
  • Rate limit
  • URL
  • Request parameters
  • Response parameters
  • Example
  • cURL request example
  • Example success response
  • Example error response
  • Status code
  • Delete a broadcast message
  • URL
  • Request parameters
  • Example
  • Example request (cURL)
  • Response
  • Status codes