Send Push-only Notification to Specific Users

App business servers can send "push notifications" to specific users. Essentially, this directly pushes a notification to App users through a third-party or self-built push channel of the IM service. This function only triggers the push, does not send a message, and does not create a conversation. It is called a "Push-only Notification for a Single User."

• Can only be sent via the IM service's server API. A maximum of 100 users can be targeted in a single push.
• The content of the "push notification" is only displayed in the notification bar. Whether the client App is in the foreground or not, it will always be displayed as a notification in the system notification bar. This function does not send a message or create a conversation, so users cannot see the content of the Push-only Notification in any chat conversation.
• The client does not store Push-only Notifications.
• 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 is offline (e.g., the App is killed), as long as it can receive pushes normally, it will receive the Push-only Notification.

tip

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

Request Method

POST: https://data center domain/push/user.json

Rate Limit: Up to 100 messages per second, with a maximum of 100 users per push. For example, sending to 100 users at once counts as 100 messages.

Signature Rule: All server API requests require rule validation. For details, 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
userIds	String[]	Yes	User IDs. A maximum of 100 users can be targeted per push.
notification	Object	Yes	Push message content by operating system type.
notification.title	String	No	Notification bar title, up to 50 characters.
notification.pushContent	String	Yes	Push message content.
notification.ios	Object	No	Settings for iOS platform push and additional information. See ios Structure Description.
notification.android	Object	No	Settings for Android platform push and additional information. See android Structure Description.
notification.harmonyOS	Object	No	Settings for HarmonyOS platform push and additional information. See harmonyOS Structure Description below.

• notification.ios Structure Description:

  Parameter	Type	Required	Description
  contentAvailable	Int	No	For 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. For details, see Knowledge Base Document. 1 means enabled, 0 means disabled. Default is 0.
  badge	int	No	App badge number, only for iOS platform; if not filled, the badge number remains unchanged; if 0 or negative, the badge number is cleared; otherwise, the badge number is set to the specified number, with a maximum of 9999. The parameter is set under the ios node. For details, refer to the "Set iOS Badge Number HTTP Request Example".
  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 collapsed.
  apns-collapse-id	String	No	iOS platform, supported from iOS10. When set, messages with the same ID received by the device will be merged into one.
  category	String	No	iOS rich text push type defined by the developer, parsed and judged by the App. Used with richMediaUri. When category is set, the push defaults to carrying mutable-content with a property value of 1.
  richMediaUri	String	No	URL of the iOS rich text push content, used with category.
  interruption-level	String	No	Applicable to iOS 15 and later. Values: passive, active (default), time-sensitive, or critical. For details, see the corresponding APNs interruption-level field. In iOS 15 and later, system "Scheduled Summary" and "Focus Mode" may cause important push notifications (e.g., balance changes) to be missed. Consider setting this field.
  extras	JSONObject	No	Additional information, if needed by the developer, can be parsed by the App.

• notification.android Structure Description

  Parameter	Type	Required	Description
  honor.importance	String	No	Honor notification bar message priority. Values: NORMAL (service and communication messages) LOW (consulting and marketing messages). If marketing messages with images are sent, the images will not be displayed.
  honor.image	String	No	Honor push custom notification bar message right large icon URL. If not set, the right icon will not be displayed. URL protocol must be HTTPS, e.g., https://example.com/image.png. Icon file must be less than 512KB, recommended size: 40dp x 40dp, corner radius: 8dp. Icons exceeding the recommended size may be compressed or partially 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 for important messages.
  hw.image	String	No	Huawei push custom notification bar message right large icon URL. If not set, the right icon will not be displayed. URL protocol must be HTTPS, e.g., https://example.com/image.png. Icon file must be less than 512KB, recommended size: 40dp x 40dp, corner radius: 8dp. Icons exceeding the recommended size may be compressed or partially displayed.
  hw.category	String	No	Huawei push channel message self-classification identifier. The 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 for this field to be valid. See Huawei push 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.
  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 right icon will not be displayed. Domestic version only supports MIUI12 and above; 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; valid when category is set. See OPUSH Message Classification Details.
  vivo.classification	String	No	VIVO push service message category. Options: 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 Explanation . This field has higher priority than the VIVO push channel type configured in the Console for the App Key's Application Identifier.
  vivo.category	String	No	VIVO push service message secondary classification. For example, IM (instant messaging). This parameter corresponds to the category field of the VIVO push service. For detailed category values, see VIVO Push Message Classification Explanation . 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 official requirements to ensure that 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 has higher priority than the VIVO push Category configured in the Console for the App Key's Application Identifier.
  fcm.channelId	String	No	Google FCM push notification channel ID. The app 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 right icon will not be displayed. Image size limit is 1MB. Requires the Console FCM push configuration to be Certificate and Notification Message Mode.
  extras	JSONObject	No	Additional information, if needed by the developer, can be parsed by the App.

• notification.harmonyOS Structure Description

  Parameter	Type	Required	Description
  alert	String	No	HarmonyOS platform push message content. If set, the default push message content is invalid.
  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. URL protocol must be HTTPS, e.g., https://example.com/image.png. Note: Supported image formats: png, jpg, jpeg, bmp. Recommended size: less than 128*128 pixels. If it exceeds 49152 pixels, the image will not be displayed.
  extras	JSONObject	No	Additional information, if needed by the developer, can be parsed by the App.

Request Example

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

{
  "userIds":["123","456"],
  "notification":{
    "title":"Title",
    "pushContent":"this is a push",
    "ios":
      {
        "thread-id":"223",
        "apns-collapse-id":"111",
        "extras": {"id": "1","name": "2"}
      },
    "android": {
        "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

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

Return Value	Return Type	Description
code	Int	Return code, 200 indicates success.

Response Example

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

{"code":200}