Broadcast to Online Users

App users can send system conversation messages to all currently online users of the app. This feature is called "Broadcast to Online Users."

• Supports sending predefined message types of the IM Service (see Message Type Overview). The message type (objectName field) determines whether the message is displayed in the chat UI, conversation list, and stored in the local database after the client receives it.
• Supports sending custom message types. Whether a custom message is displayed in the chat UI, conversation list, and stored in the local database depends on the custom message type definition registered by the client.
• Can only be sent via the IM Service Server API, with the conversation type set to SYSTEM. This type of conversation does not support replies from end users after receiving the message.

tip

• Broadcast messages are received by the client using a timed pull mechanism. After sending the message, the SDK will pull the message within a maximum of 3 minutes.
• Clients that are offline can receive the broadcast message if they come online within 10 minutes. If a client remains offline for more than 10 minutes after the message is sent, it will not receive the message.
• Online broadcast messages currently do not support recall.

For example, if the app backend wants to send a message to all users currently using the app. Assuming a text message is sent (objectName is RC:TxtMsg, which is a built-in message type that the client SDK will store and can trigger offline push notifications), the effect is as follows:

• Online users will immediately receive a message, with the Target ID of the conversation being the fromUserId passed when calling the interface, and the conversation type being system conversation (type SYSTEM).
• Offline users can still receive the broadcast message if they come online within 10 minutes. If a user remains offline for more than 10 minutes after the message is sent, they will not receive the message.

Enable the Service

Before using the Broadcast to Online Users feature, ensure that the service is enabled for the current App Key. For details, see Broadcast and Push Notification Service Configuration.

If the service is not enabled, the Server API will return a 1009 error. Note that if the service is not enabled and the API request frequency exceeds the limit due to continuous requests, the Server API will return an HTTP 429 Too Many Requests error (error code 1008).

Request Method

POST: https://Data Center Domain/message/online/broadcast.json

Rate Limit: 60 requests per minute

Signature Rule: All server API requests require signature verification. For details, see API Request Signature.

Body Parameters

The HTTP request body data format is application/x-www-form-urlencoded, and the following HTTP form parameters are supported:

Parameter	Type	Required	Description
fromUserId	String	Yes	The sender's user ID.
objectName	String	Yes	The message type, which accepts built-in message types (see Message Type Overview) or custom message type values. Note: When using custom messages, the message type must not start with "RC:" to avoid conflicts with built-in message types; the message type length must not exceed 32 characters. The custom message type must be registered in the SDK; otherwise, the SDK will not be able to parse the message.
content	String	Yes	The content of the message to be sent, with a maximum size of 128k per message. Built-in message types: Serialize the message content JSON object into a JSON string and pass it in. For the JSON structure of the message content, see the message content format of each built-in message type in Message Type Overview. For example, if the text message content JSON structure contains a content field (this is the key value within the JSON structure, note the distinction), you need to serialize {"content":"Hello world!"} and pass the result as the value of the content field here. Custom message types (objectName field must be specified as a custom message type): If sending a custom message, this parameter can be in a custom format, not limited to JSON.
disableUpdateLastMsg	Boolean	No	Disables updating the last message in the conversation. When this parameter is false, the sent message will appear in the conversation list; when true, it will not update the conversation list's message content. Note: This parameter only affects messages stored on the client.

Request Example

POST /message/online/broadcast.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Timestamp: 1585127132438
Nonce: 14314
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/x-www-form-urlencoded

content=%7B%22content%22%3A%22hello%22%2C%22extra%22%3A%22helloExtra%22%7D&fromUserId=2191&objectName=RC:TxtMsg

Response

The HTTP response body contains a JSON object with the following structure:

Return Value	Return Type	Description
code	Number	Return code, 200 indicates success.
msg	messageUID	Broadcast message ID.

Response Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "code": 200,
    "messageUID": "XXXX-JJJJ-KKK-LLLL"
}