Send Broadcast to Users

App users can send system conversation messages to all users under the App, a feature known as "Broadcast to Users."

• Supports sending predefined message types by the IM service (see Message Type Overview). The message type (objectName field) determines whether the message supports offline push notifications, and whether the client displays it in the chat UI, conversation list, and stores it in the local database after receiving the message.
• Supports sending custom message types. Whether the client displays custom messages in the chat UI, conversation list, and stores them in the local database depends on the custom message type definition registered by the client.
• Can only be sent through the IM service's server API, with the conversation type set to SYSTEM. This type of conversation does not support end-users replying to the message after receiving it.
• Broadcast messages are not stored in the IM service's historical message records by default. Therefore, if the client retrieves the server's system conversation history, it will not include broadcast messages. For storage, refer to Broadcast and Push Service Configuration.

For example, for general App business notifications, assuming a text message is sent (objectName as RC:TxtMsg, a built-in message type stored by the client SDK, and capable of triggering offline push), the effects are as follows:

• If the client is online, it will immediately receive a message, with the Target ID of the session being the fromUserId passed when calling the interface, and the session type being system conversation (type SYSTEM).
• If the client is offline, the message will trigger a server remote push. If the client has integrated and enabled the push service, it will receive a push notification.

tip

Broadcast messages are received by the client using a timed pull mechanism. After sending the message, it can be received within a maximum of 3 minutes.

Enable Service

Before using the Broadcast to Users feature, ensure that the service has been enabled for the current App Key. For details, refer to Broadcast and Push 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 continuous requests cause the API request frequency to exceed the limit, the Server API will return an HTTP 429 Too Many Requests error (error code 1008).

Request Method

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

Rate Limit: Limited to 2 times per hour, and a maximum of 3 times per day (natural day). The IM service's message processing defaults to 2000 messages per second, meaning 2000 target users can receive messages per second.

Signature Rule: All server API requests must undergo rule verification. For details, refer to API Request Signature.

Body Parameters

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

Parameter	Type	Required	Description
fromUserId	String	Yes	Sender user ID. Note: The user ID used to send the message must have obtained a user Token; otherwise, once the message triggers an offline push, the sender's user information cannot be correctly displayed in the notification.
objectName	String	Yes	Message type, accepts built-in message types (see Message Type Overview) or custom message type values. Note: For custom messages, the message type cannot start with "RC:" to avoid conflicts with system built-in message types; the message type length cannot exceed 32 characters. The SDK must have registered this custom message type; otherwise, the SDK will not be able to parse the message upon receipt.
content	String	Yes	The content of the sent message, with a maximum size of 128k per message. Built-in message types: Serialize the message content body JSON object into a JSON string and pass it in. The message content JSON structure is detailed in the message content format of each built-in message type in Message Type Overview. For example, the text message content JSON structure internally contains a content field (this is the key value within the JSON structure, note the distinction), then the serialized result of {"content":"Hello world!"} should be passed as the value of the content field here. Custom message types (objectName field must specify a custom message type): If sending a custom message, this parameter can be customized in format, not limited to JSON.
pushContent	String	No	Specifies the notification content in the remote push notification triggered when the recipient is offline. Note: For some message types, whether this field has a value determines whether a remote push notification is triggered. If the message type (objectName field) is a [user content class message format] in the IM service predefined message types, this field can be left blank, and the remote push notification will use the server's preset push notification content by default. If the message type (objectName field) is a notification class or signaling class (excluding "recall command message") in the IM service predefined message types, and remote push notification support is needed, then pushContent must be filled; otherwise, the recipient will not receive a remote push notification when offline. If remote push is not needed, this field can be left blank. If the message type is a custom message type, and remote push notification support is needed, then the pushContent field must be filled; otherwise, the recipient will not receive a remote push notification when offline. If the message type is a custom message type, but remote push notification is not needed (e.g., App business layer operation commands implemented through custom message types), the pushContent field can be left blank to disable remote push notification.
pushData	String	No	When the iOS platform receives a push message, the APNs push data can be obtained from the payload, corresponding to the field name appData (Tip: The rc field carries basic message information by default). When the Android platform receives a push message, the corresponding field name is appData.
contentAvailable	Int	No	For the iOS platform, it is a silent push when the SDK is in the background suspended state, a push method introduced after iOS7. It allows the app to run a piece of code in the background upon receiving the notification and execute it immediately. For details, refer to the Knowledge Base Document. 1 means enabled, 0 means disabled, default is 0
pushExt	String	No	Configures the push notification of the message, such as the push notification title. For details, refer to the pushExt Parameter Description below.
disableUpdateLastMsg	Boolean	No	Disables updating the last message of the conversation. When this parameter is false, the sent message will enter the conversation list; when it is true, it will not update the message content in the conversation list. Note: This parameter is only effective for messages stored on the client.

• pushExt Parameter Description

  The pushExt parameter supports setting the title of the push notification, push content template, whether to force notification, and push ChannelID, etc. pushExt requires escaping when making a JSON structure request.

  pushExt Parameter	Type	Required	Description
  title	String	No	The title displayed in the notification bar, with a maximum length of 50 characters. By default, the notification title displays the user name for one-to-one chats and the group name for group chats.
  templateId	String	No	The push template ID. After setting, it matches the language content set in the template based on the target user's language environment set through the SDK. If no match is successful, the default content is used for the push.
  forceShowPushContent	Number	No	Whether to bypass the client configuration and force the display of the notification content (pushContent) in the push notification. The default value 0 means not to force, 1 means to force. Note: Client devices can be set to only display reminders like "You have received a notification" when receiving push notifications. When sending a message from the server, setting forceShowPushContent to 1 can bypass this configuration, forcing the client to display the push content in the push notification for this message.
  pushConfigs	Array	No	Set different push attributes by vendor. Supported push channels are MI (Xiaomi), HONOR (Honor), HW (Huawei), OPPO, VIVO, APNs, FCM.
  pushConfigs.HONOR.importance	String	No	Honor notification bar message priority, values: NORMAL (Service and communication messages) LOW (Consulting and marketing messages). If marketing messages are sent with images, the images will not be displayed.
  pushConfigs.HONOR.image	String	No	Honor push custom notification bar message right-side large icon URL. If not set, the right-side icon will not be displayed. The URL must use HTTPS protocol, sample value: https://example.com/image.png. The icon file must be less than 512KB, recommended size: 40dp x 40dp, arc size: 8dp. Icons exceeding the recommended size may be compressed or not fully displayed.
  pushConfigs.HW.channelId	String	No	Huawei push notification channel ID. For details, refer to Huawei Custom Notification Channel. For more notification channel information, refer to Android Official Documentation.
  pushConfigs.HW.importance	String	No	Huawei notification bar message priority, values: NORMAL (default, important information) LOW
  pushConfigs.HW.image	String	No	Huawei push custom notification bar message right-side large icon URL. If not set, the right-side icon will not be displayed. The URL must use HTTPS protocol, sample value: https://example.com/image.png. The icon file must be less than 512KB, recommended size: 40dp x 40dp, arc size: 8dp. Icons exceeding the recommended size may be compressed or not fully displayed.
  pushConfigs.HW.category	String	No	Huawei push channel message self-classification identifier, category values must be uppercase letters, e.g., IM. The App must complete the Self-classification Rights Application or Special Permission Application as required by Huawei for this field to be valid. For details, refer to Huawei's official documentation Message Classification Standards. This field has higher priority than the Huawei push Category configured in the Console for the App Key's Application Identifier.
  pushConfigs.MI.channelId	String	No	Xiaomi push notification channel ID. For details, refer to Xiaomi Push Message Classification New Rules.
  pushConfigs.MI.large_icon_uri	String	No	Xiaomi push custom notification bar message right-side icon URL. If not set, the right-side icon will not be displayed. Domestic version only supports MIUI12 and above; international version supports. Image requirements: size 120 * 120px, format png or jpg.
  pushConfigs.OPPO.channelId	String	No	OPPO push notification channel ID. For details, refer to OPPO PUSH Channel Upgrade Instructions.
  pushConfigs.OPPO.category	String	No	Push content classification. For details, refer to OPUSH Message Classification Details.
  pushConfigs.OPPO.notify_level	Number	No	Notification reminder type, 1 notification bar, 2 notification bar + lock screen, 16 notification bar + lock screen + banner + vibration + ringtone; valid after setting category. For details, refer to OPUSH Message Classification Details.
  pushConfigs.VIVO.classification	Number	No	VIVO push service message category. Optional values 0 (operational messages, default) and 1 (system messages). This parameter corresponds to the classification field of the VIVO push service, see VIVO Push Message Classification Instructions. This field has higher priority than the VIVO push channel type configured in the Console for the App Key's Application Identifier.
  pushConfigs.VIVO.category	String	No	VIVO push service message secondary classification. E.g., IM (instant messages). This parameter corresponds to the category field of the VIVO push service. For detailed category values, refer to VIVO Push Message Classification Instructions . If category is specified, the value of the classification field matching the current secondary classification must also be passed (system message scenario or operational message scenario). Please follow VIVO's official requirements to ensure that the secondary classification (category) values belong to the content allowed to be sent under the VIVO system message scenario or operational message scenario. This field has higher priority than the VIVO push Category configured in the Console for the App Key's **Application Identifier`.
  pushConfigs.APNs.thread-id	String	No	iOS platform notification bar group ID. Push notifications with the same thread-id are grouped together, and groups with more than 5 push notifications will be folded.
  pushConfigs.APNs.apns-collapse-id	String	No	Applicable to the iOS platform. After setting, the device will merge messages with the same ID into one. Only supported on iOS 10.0 and above.
  pushConfigs.APNs.richMediaUri	String	No	Applicable to the iOS platform. iOS push custom notification bar message right-side icon URL, requires the App to parse richMediaUri and implement the display. Only supported on iOS 10.0 and above.
  pushConfigs.APNs.interruption-level	String	No	Applicable to iOS 15 and later systems. Values are passive, active (default), time-sensitive, or critical. For value descriptions, refer to the corresponding APNs interruption-level field. In iOS 15 and above, system "scheduled push summaries" and "focus modes" may cause important push notifications (e.g., balance changes) to not be promptly noticed by users. Consider setting this field.
  pushConfigs.FCM.channelId	String	No	FCM push notification channel ID. The application must first create a channel with this channel ID before it can receive any notifications with this channel ID. For more information, refer to Android Official Documentation.
  pushConfigs.FCM.collapse_key	String	No	Applicable to the Android platform. Identifier for a group of messages that can be collapsed so that only the last message is sent when delivery can be resumed.
  pushConfigs.FCM.imageUrl	String	No	For Android platform. The URL of the large icon on the right side of the FCM push notification. If not set, the icon won’t display. The image size limit is 1MB. Requires the console FCM push configuration to be Certificate and Notification Message Mode.
  pushConfigs.OHOS.category	String	No	HarmonyOS scenario-based push notification message category, e.g., IM. After completing the Classification Rights Application, this field identifies the notification message type, which affects how the message is displayed and reminded. For field values, see Request Parameter Description.
  pushConfigs.OHOS.image	String	No	The URL of the large icon on the right side of the notification. The URL must use HTTPS, e.g., https://example.com/image.png. Note: Supported image formats are PNG, JPG, JPEG, BMP. The recommended size is less than 128*128 pixels. If the size exceeds 49152 pixels, the image won’t display.

• pushExt Structure Example

  {
     "title":"you have a new message.",
     "templateId":"123456",
     "forceShowPushContent":0,
     "pushConfigs": [
         {
             "HW": {
               "channelId": "hw-123",
               "importance": "NORMAL",
               "image":"https://example.com/image.png"
             }
         },
         {
             "MI": {
               "channelId": "mi-123",
               "large_icon_uri":"https://example.com/image.png"
             }
         },
         {
             "OPPO": {
                  "channelId": "oppo-123",
                  "category": "IM",
                  "notify_level": 2
               }
         },
         {
             "VIVO" : {"classification": "0"}
         },
         {
             "APNs": {
                 "thread-id": "123",
                 "apns-collapse-id":"123456",
                 "richMediaUri":"https://example.com/image.png"
             }
         },
         {
             "FCM": {
              "channelId":"rongcloud_channelid",
              "collapse_key":"1234",
              "imageUrl":"https://example.com/image.png"
              }
         },
         {
             "OHOS": {
               "category": "IM",
               "image":"https://example.com/image.png"
             }
         }
     ]
  }

Request Example

POST /message/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&pushContent=thisisapush&pushData=%7B%22pushData%22%3A%22hello%22%7D

Response

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

Field	Type	Description
code	Number	Return code, 200 for success.
messageUID	String	Broadcast message ID.

Response Example

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

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