Android notification categories (aka notification channels) were introduced in Android 8.0 (Oreo) to give users greater control over how they receive notifications from your app. Each category defines its own settings such as sound, vibration, badge behavior, and lock screen visibility.

OneSignal makes it easy to create and manage these categories directly from the dashboard. Alternatively, you can define them programmatically in your app.

To programmatically define categories, see Android’s guide to creating notification channels.

Example of an app's notification categories on the device

​
Default notification categories

OneSignal automatically creates two default categories:

​
Miscellaneous

Used when no category is set.

  • Importance: High
  • Sound: Default
  • Vibration: Default
  • Badges: Enabled
  • Lockscreen: Private

​
Restored

Used when the app is force-quit and reopened, restoring previous notifications that were cleared.

  • Importance: Low
  • Sound: Off
  • Vibration: Off
  • Badges: Disabled
  • Lockscreen: Private

If you always send push notifications with a custom category, the “Miscellaneous” channel won’t appear on user devices. The “Restored” channel will always appear to handle restored notifications after force-closing.

​
Huawei-specific behavior

On Huawei devices, OneSignal does not set a default category. If you don’t include one, Huawei will apply High importance by default.

​
Create Android notification categories in OneSignal

  1. Go to Settings > Push & In-App > Android Notification Channels in the OneSignal Dashboard.
  2. Click Add Group to organize your categories (e.g., “News Updates”, “Social Activity”).
  3. Click Add Channel within the group to create a new category.

Where to add Android categories in OneSignal

You’ll be asked to define the following:

​
Name

User-visible. Keep it clear and descriptive.

​
Description

User-visible. Briefly explain the type of notifications this category will handle.

​
Importance

Controls how visible and interruptive the notification is:

  • Low: Silent, no alerts
  • Medium: No sound/vibration, minimal visual interruption
  • High: Plays sound or vibrates, no screen pop-up
  • Urgent: Plays sound and displays a full-screen alert

​
Sound

  • Off: No sound
  • Default: Device’s default notification tone
  • Custom: Upload and reference a custom sound (no file extension).
    Example: alert_beep (not alert_beep.wav)
    See Notification Sounds for setup instructions.

​
Vibration

  • Off: No vibration
  • Default: Uses device’s vibration pattern
  • Custom: Define your own using a pattern (in ms).
    Example: 0, 300, 500, 300 → Wait 0ms, vibrate 300ms, pause 500ms, vibrate 300ms.

​
LED Color

Some Android devices support LED indicators:

  • Off: No LED
  • Default: Device default
  • Custom: ARGB hex value (e.g., FF0000FF for blue)

​
Badges

Shows badge count on app icon:

  • Enabled: Badge is shown
  • Disabled: No badge displayed

​
Lockscreen visibility

  • Public: Full content shown
  • Private: Only app name, hides content
  • Secret: No notification visible on lock screen

Once your category is created, you can use it in your notifications.

​
Updating categories

After a device receives a notification from a category, Android locks that category’s behavior. Changes to importance, sound, vibration, or other settings will not apply retroactively.

Options:

  • To update behavior: Create a new category.
  • To test changes: Clear app data or uninstall and reinstall the app.

You can update:

  • Channel name
  • Channel group name

These will update in Android’s notification settings when the next notification is received using that updated channel.

​
Deleting categories

To remove a deleted category from the user’s device:

  1. Delete the category from the OneSignal dashboard.
  2. Ensure all notifications are cleared from the Notification Center.
  3. Have the user:
    • Put the app in the background for 60+ seconds
    • Open it again (triggers SDK sync)

The SDK will re-sync and remove the deleted category from Android settings.

​
Using categories in notifications

​
In OneSignal Dashboard

  • Go to Android Platform Settings in your message composer.
  • Select your Category under “Category”.
  • Sound, Lockscreen, and LED settings will be pulled from the category and hidden in the UI.

​
Using the REST API

Use the android_channel_id in the Create message API request.

Find the Channel ID in the Android Category setup screen

If using your own Android-defined channels, use existing_android_channel_id instead.

​
FAQ

​
Why isn’t my Android category working?

  1. Incorrect initialization: Make sure OneSignal is initialized in the Application class, not an Activity. See Android SDK Setup.
  2. Outdated category: If you changed a category after sending a push, Android may not apply those changes. Create a new category instead.

​
Can categories play sounds in Do Not Disturb (DND) mode?

No. OneSignal does not set setBypassDnd on categories. To override DND, create your own channel programmatically and enable this setting. See setBypassDnd.

​
Can I localize category names or descriptions?

No. OneSignal does not support multiple languages for categories. To support localization, define your own Android channels and reference them via existing_android_channel_id in your push API requests.

Android notification categories (aka notification channels) were introduced in Android 8.0 (Oreo) to give users greater control over how they receive notifications from your app. Each category defines its own settings such as sound, vibration, badge behavior, and lock screen visibility.

OneSignal makes it easy to create and manage these categories directly from the dashboard. Alternatively, you can define them programmatically in your app.

To programmatically define categories, see Android’s guide to creating notification channels.

Example of an app's notification categories on the device

​
Default notification categories

OneSignal automatically creates two default categories:

​
Miscellaneous

Used when no category is set.

  • Importance: High
  • Sound: Default
  • Vibration: Default
  • Badges: Enabled
  • Lockscreen: Private

​
Restored

Used when the app is force-quit and reopened, restoring previous notifications that were cleared.

  • Importance: Low
  • Sound: Off
  • Vibration: Off
  • Badges: Disabled
  • Lockscreen: Private

If you always send push notifications with a custom category, the “Miscellaneous” channel won’t appear on user devices. The “Restored” channel will always appear to handle restored notifications after force-closing.

​
Huawei-specific behavior

On Huawei devices, OneSignal does not set a default category. If you don’t include one, Huawei will apply High importance by default.

​
Create Android notification categories in OneSignal

  1. Go to Settings > Push & In-App > Android Notification Channels in the OneSignal Dashboard.
  2. Click Add Group to organize your categories (e.g., “News Updates”, “Social Activity”).
  3. Click Add Channel within the group to create a new category.

Where to add Android categories in OneSignal

You’ll be asked to define the following:

​
Name

User-visible. Keep it clear and descriptive.

​
Description

User-visible. Briefly explain the type of notifications this category will handle.

​
Importance

Controls how visible and interruptive the notification is:

  • Low: Silent, no alerts
  • Medium: No sound/vibration, minimal visual interruption
  • High: Plays sound or vibrates, no screen pop-up
  • Urgent: Plays sound and displays a full-screen alert

​
Sound

  • Off: No sound
  • Default: Device’s default notification tone
  • Custom: Upload and reference a custom sound (no file extension).
    Example: alert_beep (not alert_beep.wav)
    See Notification Sounds for setup instructions.

​
Vibration

  • Off: No vibration
  • Default: Uses device’s vibration pattern
  • Custom: Define your own using a pattern (in ms).
    Example: 0, 300, 500, 300 → Wait 0ms, vibrate 300ms, pause 500ms, vibrate 300ms.

​
LED Color

Some Android devices support LED indicators:

  • Off: No LED
  • Default: Device default
  • Custom: ARGB hex value (e.g., FF0000FF for blue)

​
Badges

Shows badge count on app icon:

  • Enabled: Badge is shown
  • Disabled: No badge displayed

​
Lockscreen visibility

  • Public: Full content shown
  • Private: Only app name, hides content
  • Secret: No notification visible on lock screen

Once your category is created, you can use it in your notifications.

​
Updating categories

After a device receives a notification from a category, Android locks that category’s behavior. Changes to importance, sound, vibration, or other settings will not apply retroactively.

Options:

  • To update behavior: Create a new category.
  • To test changes: Clear app data or uninstall and reinstall the app.

You can update:

  • Channel name
  • Channel group name

These will update in Android’s notification settings when the next notification is received using that updated channel.

​
Deleting categories

To remove a deleted category from the user’s device:

  1. Delete the category from the OneSignal dashboard.
  2. Ensure all notifications are cleared from the Notification Center.
  3. Have the user:
    • Put the app in the background for 60+ seconds
    • Open it again (triggers SDK sync)

The SDK will re-sync and remove the deleted category from Android settings.

​
Using categories in notifications

​
In OneSignal Dashboard

  • Go to Android Platform Settings in your message composer.
  • Select your Category under “Category”.
  • Sound, Lockscreen, and LED settings will be pulled from the category and hidden in the UI.

​
Using the REST API

Use the android_channel_id in the Create message API request.

Find the Channel ID in the Android Category setup screen

If using your own Android-defined channels, use existing_android_channel_id instead.

​
FAQ

​
Why isn’t my Android category working?

  1. Incorrect initialization: Make sure OneSignal is initialized in the Application class, not an Activity. See Android SDK Setup.
  2. Outdated category: If you changed a category after sending a push, Android may not apply those changes. Create a new category instead.

​
Can categories play sounds in Do Not Disturb (DND) mode?

No. OneSignal does not set setBypassDnd on categories. To override DND, create your own channel programmatically and enable this setting. See setBypassDnd.

​
Can I localize category names or descriptions?

No. OneSignal does not support multiple languages for categories. To support localization, define your own Android channels and reference them via existing_android_channel_id in your push API requests.