How do I send high-priority or time-sensitive notifications on Android and iOS?

The method for sending urgent notifications differs between Android and iOS. Below are the specific configurations and troubleshooting steps for each platform.

Android: High-Priority Notifications

On Android 8.0 (API level 26) and higher, notification behavior is managed by Notification Channels. The most important rule to remember is that a channel's settings (including its importance level) are configured only at the moment the channel is first created. Subsequent push notifications sent to an existing channel cannot change its settings.

To send a high-priority notification that can appear as a heads-up display, you must ensure it is delivered to a channel configured with high importance.

API Parameters: Use the following parameters in your /createMessage API request:

{
  "notifications": [
    {
      "android_delivery_priority": "high",
      "android_priority": 2,
      "android_root_params": {
        "pw_channel": "your_high_priority_channel_name"
      }
    }
  ]
}

Troubleshooting Steps:

If your high-priority notifications are not working as expected, it's likely because the channel was already created with a default, lower importance level. To fix this, you must force the creation of a new channel with the correct settings.

1. Use a New Channel Name: The easiest way to test is to send a push with a new, previously unused channel name in the pw_channel parameter. This will create a new channel on the device with the high-priority settings from your API request.
2. Clear App Data on the Test Device: Alternatively, you can completely reset your app's notification channels by clearing its data. Go to Settings > Apps > Your App > Storage and tap "Clear Data" or "Clear Storage". The next push you send will recreate the channels.
3. Check for Custom App Code: If your application creates notification channels manually in its own code, those settings may override the parameters sent in the push payload. Ensure your developers have set the channel's importance to IMPORTANCE_HIGH within the app's code.
4. Check Device Battery Optimization: Some manufacturers, particularly Samsung, have aggressive battery-saving features that can delay or block notifications. On your test device, check that your app is not restricted:
   • Go to Settings > Apps > Your App > Battery and set it to "Unrestricted".
   • Check that your app is not listed under "Sleeping apps" or "Deep sleeping apps" in the device's battery care section.

iOS: Time-Sensitive Notifications

On iOS, you can control how a notification interrupts the user during a Focus Mode by using the ios_interruption_level parameter.

API Parameter: Set the ios_interruption_level to time-sensitive in your API request:

{
  "notifications": [
    {
      "ios_interruption_level": "time-sensitive"
    }
  ]
}

Important Considerations:

• User Permission is Required: Your application must explicitly request authorization from the user to send Time-Sensitive notifications. This is a separate permission from the standard push notification prompt.
• "Intelligent Breakthrough" is System-Controlled: Even with time-sensitive set, iOS may still decide not to deliver the notification immediately if a Focus Mode is active. This is due to an on-device machine learning feature that analyzes a user's behavior. This system-level logic cannot be influenced or overridden via the API.
• Other Parameters (relevanceScore, userInfo): Parameters like relevanceScore are used by iOS to sort notifications within the Notification Summary, not to bypass Focus Mode. The userInfo field (sent as data or "Custom Data" in our API) is for your app's internal logic and does not affect system delivery behavior.