Send System Notification Messages

App users can send system notification messages to other users. A maximum of 100 users can be targeted in a single message. This falls under Message-bearing Notification^?.

• 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, or stores it in the local database.
• Supports sending custom message types. Whether the client displays custom messages in the chat UI, conversation list, or stores them in the local database depends on the custom message type definition registered by the client.
• System notification messages can only be sent via the IM server API, with the conversation type set to SYSTEM. This type of conversation does not support replies from end users.

Example:
For general App business notifications, 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), the effect is as follows:

• If the client is online, it will immediately receive a message with the Target ID being the fromUserId passed in the API call, and the conversation type is SYSTEM.
• If the client is offline, the message will trigger a server-side remote push. If the client has integrated and enabled the push service, it will receive a push notification.

Request Method

POST: https://[Data Center Domain](/platform-chat-api/base-url)/message/system/publish.json
Rate Limit: Up to 100 messages per second, with a maximum of 100 recipients per message. For example, sending to 100 recipients at once counts as 100 messages. Signature Rule: All server API requests require signature validation. For details, see API Request Signature.

Body Parameters

The HTTP request body is in application/x-www-form-urlencoded format and supports the following HTTP form parameters:

Parameter	Type	Required	Description
fromUserId	String	Yes	Sender's user ID. Note: The user ID used to send the message must have obtained a user Token; otherwise, if the message triggers an offline push, the sender's user information will not be correctly displayed in the notification.
toUserId	String	Yes	Recipient user ID. Providing multiple instances of this parameter allows sending system messages to multiple users, with a maximum of 100 recipients.
objectName	String	Yes	Accepts built-in message types (see Message Type Overview) or custom message type values. Note: For 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 being sent, with a maximum size of 128k. Built-in message types: Serialize the message content JSON object into a JSON string. For the JSON structure of the message content, refer to the message content format of each built-in message type in Message Type Overview. Example: The JSON structure of a text message contains a content field (note the distinction between JSON keys and values). Pass the serialized result of {"content":"Hello world!"} as the value of the content field here. Custom message types (objectName must specify a custom message type): This parameter can use a custom 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 predefined message type by the IM service of the user content class message format, this field can be left blank, and the remote push notification will use the server's predefined push notification content by default. If the message type (objectName field) is a predefined message type by the IM service of the notification class or signaling class (excluding "recall command message"), and remote push notification support is required, then pushContent must be filled in; otherwise, the recipient will not receive a remote push notification when offline. If remote push is not required, this field can be left blank. If the message type is a custom message type and remote push notification support is required, the pushContent field must be filled in; 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 required (e.g., App business layer operation commands implemented via 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 appData field (Note: The rc field carries basic message information by default). On Android, the corresponding field is also appData.
isPersisted	Int	No	Whether to store this message in the cloud storage service for the recipient's historical messages. 0 means not stored; 1 means stored. The default value is 1, stored (whether system messages are stored in the server's historical messages also depends on the Cloud Storage for One-to-One and Group Messages service). This attribute does not affect the offline message function; messages will be converted to offline messages? and stored when the user is offline. In general (cases 1 and 2), whether the client stores the message does not depend on this parameter. The following case 3 is an exception: If the message is a built-in message type, the client SDK will determine whether to store it in the local database based on the storage attribute identifier of the message type itself. See Message Type Overview. If the message is a custom message type, the client SDK will determine whether to store it in the local database based on the storage attribute identifier registered for that type on the client. If the message is a custom message type not registered on the client App (e.g., the client is using an outdated App version), the client SDK will determine whether to store the message locally based on this parameter value. However, since the message type is not registered, the client cannot parse and display the message.
contentAvailable	Int	No	For the iOS platform, this is a silent push when the SDK is in the background, 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, see Knowledge Base Document. 1 means enabled, 0 means disabled, default is 0.
disablePush	Boolean	No	Whether it is a silent message. Default false. When true, end users will not receive notification reminders when offline.
pushExt	String	No	Configures the push notification for the message, such as the push notification title, etc. This attribute is invalid when the disablePush attribute is true. For details, see the pushExt Parameter Description below.
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.

• pushExt Parameter Description

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 for one-to-one chats displays the user's name, and for group chats, it displays the group name.
templateId	String	No	Push template ID. After setting, it matches the language content set in the template based on the target user's language environment set via the SDK. If no match is found, the default content is used for the push.
forceShowPushContent	Number	No	Whether to bypass client configuration and force the display of notification content (pushContent) in the push notification. Default value 0 means not forced, 1 means forced. Note: Client devices can be configured to only display reminders like "You have received a notification" when receiving push notifications. When sending messages from the server, setting forceShowPushContent to 1 bypasses this configuration and forces 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	URL of the large icon on the right side of the custom notification bar message for Honor push. If not set, the icon on the right side of the notification bar will not be displayed. The URL must use HTTPS protocol, e.g., https://example.com/image.png. The icon file must be less than 512KB, with a recommended size of 40dp x 40dp and a corner radius of 8dp. Icons exceeding the recommended size may be compressed or not fully displayed.
pushConfigs.HW.channelId	String	No	ID of the Huawei push notification channel. For details, see Huawei Custom Notification Channel. For more information on notification channels, see Android Official Documentation.
pushConfigs.HW.importance	String	No	Huawei notification bar message priority. Values: NORMAL (default, important information) LOW
pushConfigs.HW.image	String	No	URL of the large icon on the right side of the custom notification bar message for Huawei push. If not set, the icon on the right side of the notification bar will not be displayed. The URL must use HTTPS protocol, e.g., https://example.com/image.png. The icon file must be less than 512KB, with a recommended size of 40dp x 40dp and a corner radius of 8dp. Icons exceeding the recommended size may be compressed or not fully displayed.
pushConfigs.HW.category	String	No	Huawei push channel's message self-classification identifier, where the category value must be in uppercase letters, e.g., IM. After the App completes the Self-classification Rights Application or Special Permission Application as required by Huawei, this field can be passed effectively. For details, see Huawei's official documentation Message Classification Standards. This field takes precedence over the Huawei push Category configured for the Application Identifier under the App Key in the console.
pushConfigs.MI.channelId	String	No	ID of the Xiaomi push notification channel. For details, see Xiaomi Push Message Classification New Rules.
pushConfigs.MI.large_icon_uri	String	No	URL of the icon on the right side of the custom notification bar message for Xiaomi push. If not set, the icon on the right side of the notification bar 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	ID of the OPPO push notification channel. For details, see OPPO PUSH Channel Upgrade Instructions.
pushConfigs.OPPO.category	String	No	Push content classification. For details, see 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, see 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 takes precedence over the VIVO push channel type configured for the Application Identifier under the App Key in the console.
pushConfigs.VIVO.category	String	No	VIVO push service message sub-category. For example, IM (instant messages). This parameter corresponds to the category field of the VIVO push service. For detailed category values, see VIVO Push Message Classification Instructions. If category is specified, the classification field value matching the current sub-category must also be passed (system message scenario or operational message scenario). Please follow VIVO's official requirements to ensure that the sub-category (category) values belong to the content allowed under the VIVO system message scenario or operational message scenario. This field takes precedence over the VIVO push Category configured for the Application Identifier under the App Key in the console.
pushConfigs.APNs.thread-id	String	No	iOS platform notification bar group ID. Push notifications with the same thread-id are grouped together, and a single group exceeding 5 push notifications will be collapsed.
pushConfigs.APNs.apns-collapse-id	String	No	For iOS platform. When set, messages with the same ID received by the device will be merged into one. Only supported on iOS 10.0 and above.
pushConfigs.APNs.richMediaUri	String	No	For iOS platform. URL of the icon on the right side of the custom notification bar message for iOS push. The App needs to parse richMediaUri and implement the display. Only supported on iOS 10.0 and above.
pushConfigs.APNs.interruption-level	String	No	iOS 15+ interruption level: passive, active (default), time-sensitive, critical. Affects delivery under Focus Mode.
pushConfigs.FCM.channelId	String	No	FCM notification channel ID. Requires pre-created channel. See Android Docs.
pushConfigs.FCM.collapse_key	String	No	Android message collapse key. Only the last message in a collapsed group is delivered.
pushConfigs.FCM.imageUrl	String	No	FCM notification icon URL (HTTPS, max 1MB). Requires FCM console configuration for Certificates and Notification Messages.
pushConfigs.OHOS.category	String	No	Hongmeng (HarmonyOS) scenario-based message category (e.g., IM). Requires Self-classification Rights.
pushConfigs.OHOS.image	String	No	Hongmeng notification icon URL (HTTPS). Supported formats: PNG, JPG, JPEG, BMP. It‘s recommended that the size should be smaller than 128x128px (max 49152 px).

• pushExt 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/system/publish.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&toUserId=2191&toUserId=2192&objectName=RC:TxtMsg&pushContent=thisisapush&pushData=hello

Response

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

Field	Type	Description
code	Number	Status code (200 for success).
messageUIDs	Array	List of message UIDs.
messageUIDs[i].userId	String	Recipient user ID (matches the toUserId in the request).
messageUIDs[i].messageUID	String	Unique message ID for the corresponding recipient.

---

Response Example

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

{
    "code": 200,
    "messageUIDs": [
        {
            "userId": "uid1",
            "messageUID": "XXXX-JJJJ-KKK-LLLL"
        },
        {
            "userId": "uid2",
            "messageUID": "XXXX-JJJJ-KKK-LLKL"
        }
    ]
}