Send notifications to tagged users

App users can send system messages to users with specific tags. This feature is called "Tagged User Notification".

It uses the /push.json interface.

Add or remove user tags via the Set User Tag and Batch Set User Tag interfaces.
Supports predefined message types (see Message Type Overview). The objectName field determines if the message supports offline push, and if it appears in the chat UI, conversation list, and local database.
Supports custom message types. How custom messages appear depends on how they’re defined in the client SDK.
Only available via the IM Server API with SYSTEM conversation type. Users can’t reply to these messages.

For example, sending a text message (objectName as RC:TxtMsg, a built-in message type stored by the SDK that triggers offline push) works like this:

Online clients receive the message immediately, with the Target ID as the fromUserId passed in the API call, and the conversation type as SYSTEM.
Offline clients trigger a server push. If push is enabled, they’ll receive a notification.

Enable service

Before using Tagged User Notification, ensure the service is enabled for your App Key. See Broadcast to Users Service Configuration.

If not enabled, the Server API returns a 1009 error. Exceeding the API rate limit without the service enabled returns an HTTP 429 Too Many Requests error (code 1008).

Request method

POST: https://Data Center Domain/push.json

Call frequency: Shares the /push.json rate limit—max 2 sends per hour and 3 per day. The IM Server handles 1500 tag pushes per second. Contact Business to exceed this limit.

Signature rule: All Server API requests require signature verification. See API Request Signature.

Body parameters

The HTTP request body is application/json, with this structure:

Parameter	Type	Required	Description
platform	String[]	Yes	Target OS: iOS, Android, or both. Web users also receive the message.
fromuserid	String	Yes	Sender User ID. Note: The User ID must have a User Token, or the sender’s info won’t show in offline push notifications.
audience	Object	Yes	Push conditions: User ID Push, User Tag Push (`tag`, `tag_or`), Application Package Name Push (`packageName`), or All Platform Push (`is_to_all`). Note: If `is_to_all` is `true`, other conditions are ignored.
audience.userid	String[]	No	User ID array. Max 1000 users per request. Invalid if `is_to_all` is `true`.
audience.tag	String[]	No	User tags. Max 20 tags per request, with an AND relationship. Invalid if `is_to_all` is `true`.
audience.tag_or	String[]	No	User tags. Max 20 tags per request, with an OR relationship. Invalid if `is_to_all` is `true`. Can coexist with `tag`.
audience.is_to_all	Boolean	Yes	Push to all users. `false` means push by `tag`, `tag_or`, or `userid`. `true` means push to all users, ignoring other conditions.
message.content	String	Yes	Message content. Max 128k per message. Built-in messages use JSON. See Message Type Overview for examples. Custom messages can use any format.
message.objectName	String	Yes	Message type: built-in (see Message Type Overview) or custom. Note: Custom message types can’t start with "RC:" or exceed 32 characters. Must be registered in the SDK.
message.disableUpdateLastMsg	Boolean	No	Disable updating the last message in the conversation. Only for storage type messages. `false` shows the message in the conversation list; `true` doesn’t.
notification	Object	Yes	Push notification content by OS type. If `platform` includes iOS and Android but only iOS content is set, Android uses the initial `alert`.
notification.title	String	No	Notification bar title. Max 50 characters.
notification.forceShowPushContent	Int	No	Force push content (`pushContent`) in the notification. Default `0` means no force; `1` forces it. Note: Clients can be set to show only "You received a notification." Setting this to `1` overrides that.
notification.alert	String	No	Push notification content. Note: If `notification.alert` isn’t set, you must specify `notification.ios.alert` and `notification.android.alert`. If none are set, the push fails.
notification.ios	Object	No	Push and additional info for iOS. See `ios` parameter structure.
notification.android	Object	No	Push and additional info for Android. See `android` parameter structure.
notification.harmonyOS	Object	No	Push and additional info for HarmonyOS. See `harmonyOS` structure.

notification.ios parameter structure

Parameter	Type	Required	Description
title	String	No	Push notification title. iOS 8.2+. Overrides `notification.title`.
contentAvailable	Int	No	Silent push. `1` enables it; `0` disables it. Default `0`. See Knowledge Base.
alert	String	No	Push notification content. Overrides the default.
badge	int	No	iOS app badge. Leave blank to keep the count unchanged. Set to 0 or negative to clear, or specify a number to update (max 9999). Set under the `ios` node. See "Set iOS badge count HTTP request example" for details.
thread-id	String	No	iOS notification group ID. Notifications with the same thread-id are grouped. Groups with over 5 notifications are collapsed.
apns-collapse-id	String	No	iOS 10+. Notifications with the same ID are merged into one.
category	String	No	Custom rich media push type, parsed in the app. Used with richMediaUri. When set, push defaults to mutable-content with a value of 1.
richMediaUri	String	No	URL for iOS rich media push content. Used with category.
interruption-level	String	No	iOS 15+. Values: `passive`, `active` (default), `time-sensitive`, or `critical`. See APNs interruption-level for details. In iOS 15+, scheduled notification summaries and focus mode may delay important notifications. Consider setting this field.
extras	JSONObject	No	Additional info for app parsing.

notification.android structure

Parameter	Type	Required	Description
alert	String	No	Android push notification content. Overrides default if set.
honor.importance	String	No	Honor notification priority. Values: NORMAL (service and communication messages) LOW (marketing messages). If a marketing message includes an image, the image won’t be displayed.
honor.image	String	No	URL for the large icon on the right side of Honor push notifications. If not set, the icon won’t be displayed. URL must use HTTPS protocol, e.g., `https://example.com/image.png`. Icon file must be less than 512KB, recommended size: 40dp x 40dp, corner radius: 8dp. Icons larger than the recommended size may be compressed or not fully displayed.
hw.channelId	String	No	Huawei push notification channel ID. See Custom notification channel for details.
hw.importance	String	No	Huawei push notification priority. Values: NORMAL, LOW. Default is NORMAL (important messages).
hw.image	String	No	URL for the large icon on the right side of Huawei push notifications. If not set, the icon won’t be displayed. URL must use HTTPS protocol, e.g., `https://example.com/image.png`. Icon file must be less than 512KB, recommended size: 40dp x 40dp, corner radius: 8dp. Icons larger than the recommended size may be compressed or not fully displayed.
hw.category	String	No	Self-classification ID for Huawei Push messages. Use uppercase letters, e.g., `IM`. Valid after completing the self-classification application or special permissions application. See Huawei Push docs. Overrides the Huawei Push Category in the Console’s Application Identifier.
mi.channelId	String	No	Xiaomi Push Notification Channel ID. See Xiaomi Push rules.
mi.large_icon_uri	String	No	URL for the custom notification bar icon in Xiaomi Push. If not set, the icon won’t display. Supported on MIUI12+ for domestic versions; all international versions. Image requirements: 120 * 120px, png or jpg format.
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.
oppo.notify_level	Int	No	Notification 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.
vivo.classification	String	No	VIVO Push message category: `0` (Operational Message, default) or `1` (System Message). Corresponds to VIVO Push’s `classification` field. See VIVO Push docs. Overrides the VIVO Push Channel type in the Console’s Application Identifier.
vivo.category	String	No	VIVO Push message subcategory, e.g., `IM` (Instant Message). Corresponds to VIVO Push’s `category` field. See VIVO Push docs. If `category` is set, also provide the matching `classification` value. Ensure `category` complies with VIVO’s guidelines. Overrides the VIVO Push Category in the Console’s Application Identifier.
fcm.channelId	String	No	Google FCM Push Notification Channel ID. Create a channel with this ID before receiving notifications. See Android docs.
fcm.collapse_key	String	No	Identifier for collapsing FCM messages. Only the last message is sent when delivery resumes.
fcm.imageUrl	String	No	URL for the custom notification bar icon in FCM Push. If not set, the icon won’t display. Image size limit: 1MB. Requires Certificate and Notification Message Method in the Console’s FCM Push settings.
extras	JSONObject	No	Additional info for app-side parsing.

notification.harmonyOS structure description

Parameter	Type	Required	Description
alert	String	No	Push notification content on the HarmonyOS platform. Overrides the default if provided.
ohos.category	String	No	Notification message category for scenario-based push on HarmonyOS. Identifies the notification message type after completing the self-classification rights application. Affects message display and reminder methods. For field values, see request parameter description.
ohos.image	String	No	URL for the large icon on the right side of the notification. Must use HTTPS protocol. Example: `https://example.com/image.png`. Note: Supported image formats are png, jpg, jpeg, and bmp. Recommended size is less than 128*128 pixels. Images exceeding 49152 pixels won’t be displayed.
extras	JSONObject	No	Extended information. Developers can parse this on the App side if needed.

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"],
"fromuserid": "fromuseId1",
"audience":{
    "tag":["女","年轻"],
    "tag_or":["北京","上海"],
    "userid":["123","456"],
    "is_to_all":false
},
"message": {
    "content": "{\"content\":\"1111\",\"extra\":\"aa\"}",
    "objectName": "RC:TxtMsg"
},
"notification":{
    "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

The HTTP response body is JSON with this structure:

Field	Type	Description
code	Number	Status code. 200 means success.
id	String	Push ID, same as `messageUID`.
messageUID	String	Message ID.

Response result example

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

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

IMLib

Global Chat UIKit

push notification

IMLib

Global Chat UIKit

Chat Server

Chat Server SDK

Enable service​

Request method​

Body parameters​

Request example​

Response​

Response result example​