Skip to main content

Send Application Package Name Notification

App users can send system conversation messages to all users under a specified application package name in the App. This feature is called "Application Package Name Notification."

For example, a customer creates an application through the Console, which has two clients: a student client and a teacher client (implemented by creating two application package names). When there is a need to send operational messages to all users using the student or teacher client, this feature interface can be used.

This feature uses the /push.json interface.

  • 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 will display the message in the chat UI, conversation list, and store it in the local database after receiving it.
  • Supports sending custom message types. After receiving a custom message, whether the client displays it in the chat UI, conversation list, and stores it in the local database depends on the custom message type definition registered by the client.
  • Can only be sent through the IM service server API, with the conversation type being SYSTEM. This type of conversation does not support end-users replying to the message after receiving it.

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 effects are as follows:

  • If the client is online, it will immediately receive a message. The Target ID of the conversation is the fromUserId passed when calling the interface, and the conversation type is a 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

Web users do not support this feature. End-users do not support the message reply function after receiving system messages.

Enable Service​

Before using the Application Package Name Notification feature, please confirm that the service has been enabled for the current App Key. For details, see Broadcast to Users 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). The IM service server's processing capacity for push by application package name is 2000 messages per second, meaning 2000 target users can receive messages per second.

Signature Rule: All server API requests need to be verified by rules. 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:

ParameterTypeRequiredDescription
platformString[]YesTarget operating systems, at least one of iOS and Android must be passed. If messages need to be pushed to both systems, both must be filled in. Users logged in on the Web will also receive this message when sent.
fromuseridStringYesSender user ID.

Note: The user ID used to send the message must have already obtained a user Token. Otherwise, once the message triggers an offline push, the sender's user information cannot be correctly displayed in the notification.
audienceStringYesPush condition. When using "Application Package Name Notification," set to packageName.
audience.tagString[]NoUser tags, up to 20 tags can be sent each time. Tags are in AND relationship. Invalid if is_to_all is true.
audience.tag_orString[]NoUser tags, up to 20 tags can be sent each time. Tags are in OR relationship. Invalid if is_to_all is true. tag_or and tag parameters can coexist.
audience.useridString[]NoUser IDs, up to 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. Invalid if is_to_all is true.
audience.packageNameStringNoApplication package name. Invalid if is_to_all is true. If it coexists with tag and tag_or, it is in AND relationship, pushing to users who meet all conditions. If it coexists with userid, userid takes precedence for push.
audience.is_to_allBooleanYesWhether to push to all users. false means push by tag, tag_or, or userid conditions. true means push to all users, tag, tag_or, and userid conditions are invalid.
message.contentStringYesThe content of the sent message, with a maximum 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 in the JSON structure, pay attention to distinguish), then the result of serializing {"content":"Hello world!"} is passed as the value of the content field here.

  • Custom message types (objectName field must be specified as a custom message type): If sending a custom message, this parameter can be customized in format, not limited to JSON.
message.objectNameStringYesMessage type, accepts built-in message types (see Message Type Overview) or custom message type values.

Note: When customizing 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, otherwise, the SDK will not be able to parse the message after receiving it.
message.disableUpdateLastMsgBooleanNoDisable 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 valid for messages stored in the client.
notificationObjectYesPush notification content by operating system type. If iOS and Android systems are set in the platform, but only iOS push content is set in the notification, the Android push content will be the initial alert content.
notification.titleStringNoNotification bar display title, up to 50 characters.
notification.forceShowPushContentIntNoWhether 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.

Explanation: Client devices can be set to only display 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 and force the client to display the push content in the push notification for this message.
notification.alertStringNoPush notification content. Note, if notification.alert is not passed here, notification.ios.alert and notification.android.alert must be specified separately for iOS and Android push notification content, otherwise, the push cannot be initiated normally. Once the push content for each platform is specified, the push content is subject to the alert of the corresponding platform system. If none is filled in, the push cannot be initiated.
notification.iosObjectNoSet push and additional information for the iOS platform. For details, see ios parameter structure description.
notification.androidObjectNoSet push and additional information for the Android platform. For details, see android parameter structure description.
notification.harmonyOSObjectNoSet push and additional information for the HarmonyOS platform. For details, see harmonyOS structure description.

  • notification.ios parameter structure description

    ParameterTypeRequiredDescription
    titleStringNoPush title displayed in the notification bar, only for the iOS platform, supports iOS 8.2 and above. This property has higher priority than notification.title.
    contentAvailableIntNoFor 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 can be executed immediately. For details, see Knowledge Base Document. 1 means enabled, 0 means disabled, default is 0
    alertStringNoPush notification content, after passing in, the default push notification content is invalid.
    badgeintNoApp badge, only for the iOS platform; if not filled in, it means not changing the badge number; if it is 0 or a negative number, it means clearing the number on the App badge; otherwise, pass the corresponding number to change the badge number to the specified number, the maximum does not exceed 9999, the parameter is set under the ios node, for details, refer to "Set iOS Badge Number HTTP Request Example".
    thread-idStringNoiOS platform notification bar group ID, pushes with the same thread-id are grouped together, and a single group with more than 5 pushes will be folded for display.
    apns-collapse-idStringNoiOS platform, supported from iOS10, after setting, the device will merge messages with the same ID into one.
    categoryStringNoiOS rich text push type is defined by the developer themselves, parsed and judged by the App side, used together with richMediaUri, when category is set, the push will carry mutable-content by default, the attribute value is 1.
    richMediaUriStringNoiOS rich text push content URL, used together with category.
    interruption-levelStringNoApplicable to iOS 15 and later systems. The value is passive, active (default), time-sensitive, or critical, for value descriptions, see the corresponding APNs interruption-level field. In iOS 15 and later versions, the system's "scheduled push summary" and "focus mode" may cause important push notifications (such as balance changes) to not be perceived by users in time. Consider setting this field.
    extrasJSONObjectNoAdditional information, if the developer needs it, they can parse it themselves on the App side.
    • notification.android structure description
    ParameterTypeRequiredDescription
    alertStringNoAndroid platform push notification content, after passing in, the default push notification content is invalid.
    honor.importanceStringNoHonor notification bar message priority, value:
    • NORMAL (service and communication messages)
    • LOW (consulting and marketing messages). If consulting and marketing messages are sent with images, the images will not be displayed.
    honor.imageStringNoHonor 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 protocol, value example: https://example.com/image.png.
    • The icon file must be less than 512KB, the recommended icon size is 40dp x 40dp, the arc size is 8dp.
      Icons exceeding the recommended size may be compressed or not fully displayed.
    hw.channelIdStringNoHuawei push notification channel ID. For details, see Custom Notification Channel.
    hw.importanceStringNoHuawei push notification bar message priority, value NORMAL, LOW, default is NORMAL important message.
    hw.imageStringNoHuawei 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 protocol, value example: https://example.com/image.png. The icon file must be less than 512KB, the recommended icon size is 40dp x 40dp, the arc size is 8dp, icons exceeding the recommended size may be compressed or not fully displayed.
    hw.categoryStringNoHuawei push channel message self-classification identifier, category value must be uppercase letters, such as IM. App must complete Self-classification Rights Application or Special Permission Application according to Huawei requirements before passing this field effectively. For details, see Huawei push official document Message Classification Standard. This field has higher priority than the Huawei push Category configured for the App Key in the Console.
    mi.channelIdStringNoXiaomi push notification channel ID. For details, see Xiaomi Push Message Classification New Rules.
    mi.large_icon_uriStringNoXiaomi 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 are not supported; international version supports. Image requirements: size 120 * 120px, format png or jpg.
    oppo.channelIdStringNoOPPO push notification channel ID. For details, see Push Private Channel Application.
    oppo.categoryStringNoPush content classification. For details, see OPUSH Message Classification Details.
    oppo.notify_levelNumberNoNotification 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.
    vivo.classificationStringNoVIVO push service message category. Optional value 0 (operational message, default value) and 1 (system message). This parameter corresponds to the classification field of the VIVO push service, see VIVO Push Message Classification Description. This field has higher priority than the VIVO push channel type configured for the App Key in the Console.
    vivo.categoryStringNoVIVO push service message secondary classification. For example IM (instant message). This parameter corresponds to the category field of the VIVO push service. 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 in at the same time. 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 for the App Key in the Console.
    fcm.channelIdStringNoGoogle 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_keyStringNoGoogle 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.imageUrlStringNoGoogle 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.
    extrasJSONObjectNoAdditional information, if the developer needs it, they can parse it themselves on the App side.

  • notification.harmonyOS structure description

    ParameterTypeRequiredDescription
    alertStringNoHarmonyOS platform push message content, after passing in, the default push message content is invalid.
    ohos.categoryStringNoHarmonyOS system scenario push notification message category. After completing Self-classification Rights Application, it is used to identify the notification message type, different notification message types affect the message display and reminder method. Field values see [Request Parameter Description](https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V5/push-scenariozed-api-request-param-V
Last updated on