Send Push-only Notification to All Users

The App business end can send push notifications to all users or specified user groups, which is essentially directly pushing a notification to all users in the App through a third-party or self-built push channel of the IM service. This function only triggers push notifications and does not send messages or create conversations, known as "Push-only Notification to All Users."

This function uses the /push.json interface.

It can only be sent through the IM service's Server API.
All content of the "Push Notification" is displayed only in the notification bar. Whether the client App is in the foreground or not, it will always be displayed in the system notification bar as a notification. This function does not send messages or create conversations, so users cannot see the content of the Push-only Notification in any chat conversation.
The client will not store Push-only Notifications.
It always uses the push channel, so it is not affected by the connection status between the client and the IM service. Even if the client is not in the foreground or online (e.g., the App is killed), as long as it can receive push notifications normally, it will receive the Push-only Notification.
The audience field can control the push conditions, supporting user tags (tag), user IDs (userid), application package names (packageName), and all users (is_to_all). User tags need to be set by the App, see Set User Tags and Batch Set User Tags.

tip

The IM service considers devices that have connected to the IM service within the last 30 days as the target for push notifications. Devices that have not opened the App for 30 days are considered uninstalled.
If the client device does not allow push notifications (set to disallow push notifications when disconnected), or if the push fails for other reasons, the Push-only Notification will not be received.

Enable the Service

Before using the Push-only Notification to All Users function, please ensure that the relevant service has been enabled for the current App Key. See 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/push.json

Rate Limit: Shares the rate limit quota of /push.json, i.e., a maximum of 2 times per hour and 3 times per day (natural day).

Signature Rule: All Server API requests require rule verification, see API Request Signature.

Body Parameters

The HTTP request body data format is application/json, containing a JSON object with the following structure:

Parameter	Type	Required	Description
platform	String[]	Yes	Target operating systems, at least one of iOS or Android must be passed. If messages need to be pushed to both systems, both must be filled.
audience	Object	Yes	Push conditions, including: tag, userid, packageName, is_to_all.
audience.tag	String[]	No	User tags. A maximum of 20 tags can be sent each time, with an AND relationship between tags. This parameter is invalid if `is_to_all` is true.
audience.tag_or	String[]	No	User tags. A maximum of 20 tags can be sent each time, with an OR relationship between tags. This parameter is invalid if `is_to_all` is true. The tag_or parameter can coexist with the tag parameter.
audience.userid	String[]	No	User IDs, a maximum of 1000 users can be sent each time. If both tag and userid conditions exist, userid takes precedence. If userid has a value, the platform parameter is invalid. This parameter is invalid if `is_to_all` is true.
audience.packageName	String	No	Application package name. This parameter is invalid if `is_to_all` is true. If it coexists with tag or tag_or, it has an AND relationship, pushing to users who meet all conditions. If it coexists with userid, userid takes precedence.
audience.is_to_all	Boolean	Yes	Whether to push to all users. False means pushing according to tag, tag_or, or userid conditions. True means pushing to all users, making tag, tag_or, and userid conditions invalid.
notification	Object	Yes	Push message content by operating system type. If iOS and Android are set in the platform but only iOS push content is set in `notification`, the Android push content will be the initial alert setting. See `notification` Parameter Structure Description.
notification.title	String	No	Notification bar display title, maximum 50 characters.
notification.forceShowPushContent	Int	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 set to display only reminders like "You have received a notification" when receiving push notifications. When sending messages 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.
notification.alert	String	No	Default push notification content. If alert under iOS or Android is filled, the push content will follow the alert of the corresponding platform.
notification.ios	Object	No	Set push and additional information for the iOS platform. See `ios` Parameter Structure Description.
notification.android	Object	No	Set push and additional information for the Android platform. See `android` Parameter Structure Description.
notification.harmonyOS	Object	No	Set push and additional information for the HarmonyOS platform. See below for `harmonyOS` Structure Description.

notification.ios Parameter Structure Description

Parameter	Type	Required	Description
title	String	No	Push title displayed in the notification bar, only for the iOS platform, supporting iOS 8.2 and above. This property takes precedence over `notification.title`.
contentAvailable	Int	No	For the iOS platform, silent push is a push method introduced after iOS7. It allows the App to run a piece of code in the background after receiving the notification and execute it immediately. See Knowledge Base Document for details. 1 means enabled, 0 means disabled, default is 0
alert	String	No	Push message content, invalidates the default push message content after being passed, cannot be empty.
badge	int	No	App badge, only for the iOS platform; if not filled, the badge number remains unchanged; if 0 or negative, the App badge number is cleared; otherwise, the corresponding number indicates changing the badge number to the specified number, maximum 9999. The parameter is set under the `ios` node, see "Set iOS Badge Number HTTP Request Example" for details.
thread-id	String	No	iOS platform notification bar grouping ID, pushes with the same thread-id are grouped together, and more than 5 pushes in a single group will be folded.
apns-collapse-id	String	No	iOS platform, supported from iOS10, setting this ID will merge messages with the same ID into one.
category	String	No	iOS rich text push type defined by the developer, parsed and judged by the App side, used with richMediaUri. When category is set, the push will carry mutable-content by default, with a property value of 1.
richMediaUri	String	No	iOS rich text push content URL, used with category.
interruption-level	String	No	Applicable to iOS 15 and later systems. Values are `passive`, `active` (default), `time-sensitive`, or `critical`. For details, see the corresponding APNs interruption-level field. In iOS 15 and above, system "Scheduled Summary" and "Focus Mode" may cause important push notifications (e.g., balance changes) to be unnoticed by users in time. Consider setting this field.
extras	JSONObject	No	Additional information, if needed by the developer, can be parsed by the App side.

notification.android Structure Description

Parameter	Type	Required	Description
alert	String	No	Android platform push message content, invalidates the default push message content after being passed.
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.
honor.image	String	No	Honor push custom notification bar message right large icon URL, if not set, the notification bar right icon will not be displayed. The URL protocol must be HTTPS, 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.
hw.channelId	String	No	Huawei push notification channel ID. See Custom Notification Channel.
hw.importance	String	No	Huawei push notification bar message priority, values NORMAL, LOW, default is NORMAL important message.
hw.image	String	No	Huawei push custom notification bar message right large icon URL, if not set, the notification bar right icon will not be displayed. The URL protocol must be HTTPS, 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.
hw.category	String	No	Huawei push channel message self-classification identifier, category value must be uppercase letters, e.g., `IM`. The App must complete the Self-classification Rights Application or Special Permission Application as required by Huawei to make this field valid. See Huawei push official document Message Classification Standards. This field takes precedence over the Huawei push Category configured for the App Key's Application Identifier in the Console.
mi.channelId	String	No	Xiaomi push notification channel ID. See Xiaomi Push Message Classification New Rules.
mi.large_icon_uri	String	No	Xiaomi push custom notification bar message right icon URL, if not set, the notification bar right icon will not be displayed. Domestic version only supports MIUI12 and above, below versions do not support; international version supports. Image requirements: size 120 * 120px, format png or jpg.
oppo.channelId	String	No	OPPO push notification channel ID. See Push Private Channel Application.
oppo.category	String	No	Push content classification. See OPUSH Message Classification Details.
oppo.notify_level	Number	No	Notification reminder type, 1 notification bar, 2 notification bar + lock screen, 16 notification bar + lock screen + banner + vibration + ringtone; this field is valid after setting category. See OPUSH Message Classification Details.
vivo.classification	String	No	VIVO push service message category. Optional values `0` (operational messages, default) and `1` (system messages). This parameter corresponds to the VIVO push service's `classification` field, see VIVO Push Message Classification Description . This field takes precedence over the VIVO push channel type configured for the App Key's Application Identifier in the Console.
vivo.category	String	No	VIVO push service message secondary classification. E.g., `IM` (instant messages). This parameter corresponds to the VIVO push service's `category` field. For detailed category values, see VIVO Push Message Classification Description . If `category` is specified, the `classification` field value matching the current secondary classification (system message scenario or operational message scenario) must be passed at the same time. Please follow VIVO official requirements to ensure the secondary classification (`category`) value belongs to the content allowed to be sent under the VIVO system message scenario or operational message scenario. This field takes precedence over the VIVO push Category configured for the App Key's Application Identifier in the Console.
fcm.channelId	String	No	Google 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, see Android Official Documentation.
fcm.collapse_key	String	No	Google FCM push identifier for a group of messages that can be collapsed so that only the last message is sent when delivery can be resumed.
fcm.imageUrl	String	No	Google FCM push custom notification bar message right icon URL, if not set, the notification bar right icon will not be displayed. The image size limit is 1MB. Requires the Console FCM push configuration to be Certificate and Notification Message Method.
extras	JSONObject	No	Additional information, if needed by the developer, can be parsed by the App side.

notification.harmonyOS Structure Description

Parameter	Type	Required	Description
alert	String	No	HarmonyOS platform push message content, invalidates the default push message content after being passed.
ohos.category	String	No	HarmonyOS scenario-based push notification message category. After completing the Self-classification Rights Application, it is used to identify the notification message type, which affects the message display and reminder method. Field values see Request Parameter Description.
ohos.image	String	No	Notification right large icon URL, the URL protocol must be HTTPS, sample value: `https://example.com/image.png`. Note: Supported image formats are png, jpg, jpeg, bmp, image length * width recommended to be less than 128*128 pixels, if exceeding 49152 pixels, the image will not be displayed.
extras	JSONObject	No	Additional information, if needed by the developer, can be parsed by the App side.

Request Example

POST /push.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1585127132438
Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
Content-Type: application/json

{
  "platform":["ios","android"],
  "audience":{
    "tag":["female","young"],
    "tag_or":["Beijing","Shanghai"],
    "userid":["123","456"],
    "is_to_all":true
  },
  "notification":{
    "title":"Title",
    "forceShowPushContent":0,
    "alert":"this is a push",
    "ios":
      {
        "alert": "override alert",
        "thread-id":"223",
        "apns-collapse-id":"111",
        "extras": {"id": "1","name": "2"}
      },
    "android": {
        "alert": "override alert",
        "hw":{
            "channelId":"NotificationKanong",
            "importance": "NORMAL",
            "image":"https://example.com/image.png"
        },
        "mi":{
            "channelId":"rongcloud_kanong",
            "large_icon_uri":"https://example.com/image.png"
        },
        "oppo":{
            "channelId":"rc_notification_id",
            "category": "IM",
            "notify_level": 2
        }, 
        "vivo":{
            "classification":"0"
        },
        "extras": {"id": "1","name": "2"}
      },
      "harmonyOS": {
            "ohos":{
                "category":"IM",
                "image":"https://example.com/image.png"
            },
            "extras": {"id": "1","name": "2"}
      }
  }
}

Response Result

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

Return Value	Type	Description
code	Number	Return code, 200 indicates success.
id	String	The unique identifier for the push.

Response Example

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

{"code":200,"id":"50whSR6kQiHb7YgFwQzXIb"}

IMLib

Global Chat UIKit

push notification

IMLib

Global Chat UIKit

Chat Server

Chat Server SDK

Enable the Service​

Request Method​

Body Parameters​

Request Example​

Response Result​

Response Example​