Create and Manage Notification Channels

Starting in Android 8.0 (API level 26), all notifications must be assigned to a channel. For each channel, you can set the visual and auditory behavior that is applied to all notifications in that channel. Then, users can change these settings and decide which notification channels from your app should be intrusive or visible at all.

Check out the video below for an overview of channels and other new notification features in Android 8.0.

For sample code that uses notifications, including Android 8.0 features, see the Android Notifications Sample.

The user settings for notification channels are available for each app in the system settings, as shown in figure 1.

Figure 1. Notification settings for the Clock app and one of its channels

Note: The user interface refers to notification channels as "categories."

After you create a notification channel, you cannot change the notification behaviors—the user has complete control at that point. Though you can still change a channel's name and description.

You should create a channel for each distinct type of notification you need to send. You can also create notification channels to reflect choices made by users of your app. For example, you can set up separate notification channels for each conversation group created by a user in a messaging app.

When you target Android 8.0 (API level 26), you must implement one or more notification channels. If your targetSdkVersion is set to 25 or lower, when your app runs on Android 8.0 (API level 26) or higher, it behaves the same as it would on devices running Android 7.1 (API level 25) or lower.

Caution: If you target Android 8.0 (API level 26) and post a notification without specifying a notification channel, the notification does not appear and the system logs an error.

Note: You can turn on a new setting in Android 8.0 (API level 26) to display an on-screen warning that appears as a toast when an app targeting Android 8.0 (API level 26) attempts to post without a notification channel. To turn on the setting for a development device running Android 8.0 (API level 26), navigate to Settings > Developer options and enable Show notification channel warnings.

Create a notification channel

To create a notification channel, follow these steps:

1. Construct a NotificationChannel object with a unique channel ID, a user-visible name, and an importance level.
2. Optionally, specify the description that the user sees in the system settings with setDescription().
3. Register the notification channel by passing it to createNotificationChannel().

Caution: You should guard this code with a condition on the SDK_INT version to run only on Android 8.0 (API level 26) and higher, because the notification channels APIs are not available in the support library.

Kotlin

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    // Create the NotificationChannel
    val name = getString(R.string.channel_name)
    val descriptionText = getString(R.string.channel_description)
    val importance = NotificationManager.IMPORTANCE_DEFAULT
    val mChannel = NotificationChannel(CHANNEL_ID, name, importance)
    mChannel.description = descriptionText
    // Register the channel with the system; you can't change the importance
    // or other notification behaviors after this
    val notificationManager = getSystemService(NOTIFICATION_SERVICE) as NotificationManager
    notificationManager.createNotificationChannel(mChannel)
}

Java

private void createNotificationChannel() {
    // Create the NotificationChannel, but only on API 26+ because
    // the NotificationChannel class is new and not in the support library
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        CharSequence name = getString(R.string.channel_name);
        String description = getString(R.string.channel_description);
        int importance = NotificationManager.IMPORTANCE_DEFAULT;
        NotificationChannel channel = new NotificationChannel(CHANNEL_ID, name, importance);
        channel.setDescription(description);
        // Register the channel with the system; you can't change the importance
        // or other notification behaviors after this
        NotificationManager notificationManager = getSystemService(NotificationManager.class);
        notificationManager.createNotificationChannel(channel);
    }
}

Creating an existing notification channel with its original values performs no operation, so it's safe to call this code when starting an app.

By default, all notifications posted to this channel use the visual and auditory behaviors defined by the importance level from the NotificationManagerCompat class, such as IMPORTANCE_DEFAULT and IMPORTANCE_HIGH. (See below for more information about importance levels.)

If you'd like to further customize your channel's default notification behaviors, you can call methods such as enableLights(), setLightColor(), and setVibrationPattern() on the NotificationChannel. But remember that once you create the channel, you cannot change these settings and the user has final control of whether these behaviors are active.

You can also create multiple notification channels in a single operation by calling createNotificationChannels().

Note: In addition to adding each notification to your app-specific channels, you should consider adding each notification to one of the system-wide categories (such as "Alarms" and "Reminders").

Set the importance level

Channel importance affects the interruption level of all notifications posted in the channel, and you must specify it in the NotificationChannel constructor. You can use one of five importance levels, ranging from IMPORTANCE_NONE(0) to IMPORTANCE_HIGH(4). The importance level you assign to a channel applies to all notification messages that you post to it.

To support devices running Android 7.1 (API level 25) or lower, you must also call setPriority() for each notification, using a priority constant from the NotificationCompat class.

The importance (NotificationManager.IMPORTANCE_*) and priority constants (NotificationCompat.PRIORITY_*) map to the user-visible importance options as indicated in table 1.

Table 1. Channel importance levels

User-visible importance level	Importance (Android 8.0 and higher)	Priority (Android 7.1 and lower)
Urgent Makes a sound and appears as a heads-up notification	IMPORTANCE_HIGH	PRIORITY_HIGH or PRIORITY_MAX
High Makes a sound	IMPORTANCE_DEFAULT	PRIORITY_DEFAULT
Medium No sound	IMPORTANCE_LOW	PRIORITY_LOW
Low No sound and does not appear in the status bar	IMPORTANCE_MIN	PRIORITY_MIN

All notifications, regardless of importance, appear in non-interruptive system UI locations, such as in the notification drawer and as a badge on the launcher icon, though you can modify the appearance of the notification badge.

Once you submit the channel to the NotificationManager, you cannot change the importance level. However, the user can change their preferences for your app's channels at any time.

For information about choosing an appropriate priority level, see "Priority levels" in the Notifications design guide.

Read notification channel settings

Users can modify the settings for notification channels, including behaviors such as vibration and alert sound. So if you'd like to know the settings a user has applied to your notification channels, follow these steps:

1. Get the NotificationChannel object by calling either getNotificationChannel() or getNotificationChannels().
2. Query specific channel settings such as getVibrationPattern(), getSound(), and getImportance().

Then, if you detect a channel setting that you believe inhibits the intended behavior for your app, you can suggest the user change it and provide an action to open the channel settings (see the next section).

Open the notification channel settings

After you create a notification channel, you cannot change the notification channel's visual and auditory behaviors programmatically—only the user can change the channel behaviors from the system settings. To provide your users easy access to these notification settings, you should add an item in your app's settings UI that opens these system settings.

You can open the system settings for notification channels with an Intent that uses the ACTION_CHANNEL_NOTIFICATION_SETTINGS action.

For example, the following sample code shows how you can redirect a user to the settings for a notification channel:

Kotlin

val intent = Intent(Settings.ACTION_CHANNEL_NOTIFICATION_SETTINGS).apply {
    putExtra(Settings.EXTRA_APP_PACKAGE, packageName)
    putExtra(Settings.EXTRA_CHANNEL_ID, myNotificationChannel.getId())
}
startActivity(intent)

Java

Intent intent = new Intent(Settings.ACTION_CHANNEL_NOTIFICATION_SETTINGS);
intent.putExtra(Settings.EXTRA_APP_PACKAGE, getPackageName());
intent.putExtra(Settings.EXTRA_CHANNEL_ID, myNotificationChannel.getId());
startActivity(intent);

Notice that the intent requires two extras that specify your app's package name (also known as the application ID) and the channel to edit.

Delete a notification channel

You can delete notification channels by calling deleteNotificationChannel(). The following sample code demonstrates how to complete this process:

Kotlin

// The id of the channel.
val notificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
val id: String = "my_channel_01"
notificationManager.deleteNotificationChannel(id)

Java

NotificationManager notificationManager =
        (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
// The id of the channel.
String id = "my_channel_01";
notificationManager.deleteNotificationChannel(id);

Note: The notification settings screen displays the number of deleted channels, as a spam prevention mechanism. You can clear test channels on development devices either by reinstalling the app or by clearing the data associated with your copy of the app.

Create a notification channel group

If you'd like to further organize the appearance of your channels in the settings UI, you can create channel groups. This is a good idea when your app supports multiple user accounts (such as for work profiles), so you can create a notification channel group for each account. This way, users can easily identify and control multiple notification channels that have identical names.

Figure 2. Notification channel settings with groups for personal and work accounts

For example, a social networking app might include support for personal and work accounts. In this scenario, each account might require multiple notification channels with identical functions and names, such as the following:

• A personal account with two channels:
  • New comments
  • Post recommendations
• A business account with two channels:
  • New comments
  • Post recommendations

Organizing the notification channels into groups for each account ensures that users can easily distinguish between them.

Each notification channel group requires an ID that must be unique within your package, as well as a user-visible name. The following snippet demonstrates how to create a notification channel group.

Kotlin

// The id of the group.
val groupId = "my_group_01"
// The user-visible name of the group.
val groupName = getString(R.string.group_name)
val notificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
notificationManager.createNotificationChannelGroup(NotificationChannelGroup(groupId, groupName))

Java

// The id of the group.
String groupId = "my_group_01";
// The user-visible name of the group.
CharSequence groupName = getString(R.string.group_name);
NotificationManager notificationManager =
        (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
mNotificationManager.createNotificationChannelGroup(new NotificationChannelGroup(groupId, groupName));

After you've created a new group, you can call setGroup() to associate a new NotificationChannel object with the group.

Once you submit the channel to the notification manager, you cannot change the association between notification channel and group.