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

Note (2026): /createMessage is deprecated. New integrations should use the unified Messaging API v2 Notify endpoint; see the migration guide for a field-by-field mapping. The parameters below still work on /createMessage and map 1:1 to v2.

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 (android_priority accepts -2 to 2; android_delivery_priority accepts normal or high):

{
  "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.

• 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 creates a new channel on the device with the high-priority settings from your API request.
• Clear app data on the test device: alternatively, 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 will recreate the channels.
• 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.
• Check device battery optimization: some manufacturers, particularly Samsung, have aggressive battery-saving features that can delay or block notifications. On your test device, set Settings > Apps > Your App > Battery to "Unrestricted", and 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 15 and later you can control how a notification interrupts the user during a Focus mode by using the ios_interruption_level parameter. Supported values are passive, active, time-sensitive and critical.

{
  "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 on-device machine-learning behavior cannot be influenced or overridden via the API.
• Other parameters (relevanceScore, userInfo): relevanceScore is used by iOS to sort notifications within the Notification Summary, not to bypass Focus mode. The userInfo field (sent as data or "Custom Data") is for your app's internal logic and does not affect system delivery behavior.
• Critical alerts: the critical interruption level additionally requires an Apple-granted Critical Alerts entitlement for your app.