Create a Group of Notifications

Stay organized with collections Save and categorize content based on your preferences.

Starting in Android 7.0 (API level 24), you can choose to display related notifications in a group (previously called "bundled" notifications). For example, if your app shows notifications for received emails, you should put all notifications into the same group so they can be collapsed together.

To support older versions, you must also add a summary notification that appears alone to summarize all the separate notifications—this is often best done with the inbox-style notification.

Figure 1. A collapsed and expanded notification group

You should use notification groups if all of the following conditions are true for your use case:

  • The child notifications are complete notifications and can be displayed individually without the need for a group summary.
  • There is a benefit to surfacing the child notifications individually. For example:
    • They are actionable, with actions specific to each notification.
    • There is more information in each notification that the user should see.

If your notifications don't meet the above criteria, you should instead consider updating an existing notification with new information or create a message-style notification to show multiple updates in the same conversation.

Create a group and add a notification to it

To create a notification group, define a unique identifier string for the group. Then, for each notification you want in the group, just call setGroup(), passing the group name. For example:

Kotlin

val GROUP_KEY_WORK_EMAIL = "com.android.example.WORK_EMAIL"

val newMessageNotification = NotificationCompat.Builder(this@MainActivity, CHANNEL_ID)
        .setSmallIcon(R.drawable.new_mail)
        .setContentTitle(emailObject.getSenderName())
        .setContentText(emailObject.getSubject())
        .setLargeIcon(emailObject.getSenderAvatar())
        .setGroup(GROUP_KEY_WORK_EMAIL)
        .build()

Java

String GROUP_KEY_WORK_EMAIL = "com.android.example.WORK_EMAIL";

Notification newMessageNotification = new NotificationCompat.Builder(MainActivity.this, CHANNEL_ID)
        .setSmallIcon(R.drawable.new_mail)
        .setContentTitle(emailObject.getSenderName())
        .setContentText(emailObject.getSubject())
        .setLargeIcon(emailObject.getSenderAvatar())
        .setGroup(GROUP_KEY_WORK_EMAIL)
        .build();

By default, notifications are sorted according to when they were posted, but you can change order by calling setSortKey().

If alerts for a notification's group should be handled by a different notification, call setGroupAlertBehavior(). For example, if you want only the summary of your group to make noise, all children in the group should have the group alert behavior GROUP_ALERT_SUMMARY. The other options are GROUP_ALERT_ALL and GROUP_ALERT_CHILDREN.

Set a group summary

Grouped notifications must have an extra notification which acts as the group summary. To enable grouped notifications, you must set a group summary. This group summary should include some of the text from each of the other notifications in the group, to help the user understand what is in the group. How the group summary is displayed depends on the Android version:

  • On Android versions lower than 7.0 (API level 24), which cannot show a nested group of notifications, the system only shows your group summary notification, and hides all the others. The user can tap the group summary notification to open your app.

  • On Android 7.0 and higher, the system shows your group summary notification as a nested group of notifications, labeled with snippets of text from each grouped notification; it does not display the text you set on the group summary notification. The user can expand the nested group of notifications to see the individual notifications in the group, as shown in figure 1.

Note that even if newer versions of Android don't show the group summary text that you designed, you always need to manually set a summary to enable grouped notifications. The behavior of the group summary might vary on some device types such as wearables. Setting rich content on your group summary helps ensure the best experience on all devices and versions.

To add a group summary, proceed as follows:

  1. Create a new notification with a description of the group—often best done with the inbox-style notification.
  2. Add the summary notification to the group by calling setGroup().
  3. Specify that it should be used as the group summary by calling setGroupSummary(true).

For example:

Kotlin

//use constant ID for notification used as group summary
val SUMMARY_ID = 0
val GROUP_KEY_WORK_EMAIL = "com.android.example.WORK_EMAIL"

val newMessageNotification1 = NotificationCompat.Builder(this@MainActivity, CHANNEL_ID)
        .setSmallIcon(R.drawable.ic_notify_email_status)
        .setContentTitle(emailObject1.getSummary())
        .setContentText("You will not believe...")
        .setGroup(GROUP_KEY_WORK_EMAIL)
        .build()

val newMessageNotification2 = NotificationCompat.Builder(this@MainActivity, CHANNEL_ID)
        .setSmallIcon(R.drawable.ic_notify_email_status)
        .setContentTitle(emailObject2.getSummary())
        .setContentText("Please join us to celebrate the...")
        .setGroup(GROUP_KEY_WORK_EMAIL)
        .build()

val summaryNotification = NotificationCompat.Builder(this@MainActivity, CHANNEL_ID)
        .setContentTitle(emailObject.getSummary())
        //set content text to support devices running API level < 24
        .setContentText("Two new messages")
        .setSmallIcon(R.drawable.ic_notify_summary_status)
        //build summary info into InboxStyle template
        .setStyle(NotificationCompat.InboxStyle()
                .addLine("Alex Faarborg Check this out")
                .addLine("Jeff Chang Launch Party")
                .setBigContentTitle("2 new messages")
                .setSummaryText("janedoe@example.com"))
        //specify which group this notification belongs to
        .setGroup(GROUP_KEY_WORK_EMAIL)
        //set this notification as the summary for the group
        .setGroupSummary(true)
        .build()

NotificationManagerCompat.from(this).apply {
    notify(emailNotificationId1, newMessageNotification1)
    notify(emailNotificationId2, newMessageNotification2)
    notify(SUMMARY_ID, summaryNotification)
}

Java

//use constant ID for notification used as group summary
int SUMMARY_ID = 0;
String GROUP_KEY_WORK_EMAIL = "com.android.example.WORK_EMAIL";

Notification newMessageNotification1 =
    new NotificationCompat.Builder(MainActivity.this, CHANNEL_ID)
        .setSmallIcon(R.drawable.ic_notify_email_status)
        .setContentTitle(emailObject1.getSummary())
        .setContentText("You will not believe...")
        .setGroup(GROUP_KEY_WORK_EMAIL)
        .build();

Notification newMessageNotification2 =
    new NotificationCompat.Builder(MainActivity.this, CHANNEL_ID)
        .setSmallIcon(R.drawable.ic_notify_email_status)
        .setContentTitle(emailObject2.getSummary())
        .setContentText("Please join us to celebrate the...")
        .setGroup(GROUP_KEY_WORK_EMAIL)
        .build();

Notification summaryNotification =
    new NotificationCompat.Builder(MainActivity.this, CHANNEL_ID)
        .setContentTitle(emailObject.getSummary())
        //set content text to support devices running API level < 24
        .setContentText("Two new messages")
        .setSmallIcon(R.drawable.ic_notify_summary_status)
        //build summary info into InboxStyle template
        .setStyle(new NotificationCompat.InboxStyle()
                .addLine("Alex Faarborg  Check this out")
                .addLine("Jeff Chang    Launch Party")
                .setBigContentTitle("2 new messages")
                .setSummaryText("janedoe@example.com"))
        //specify which group this notification belongs to
        .setGroup(GROUP_KEY_WORK_EMAIL)
        //set this notification as the summary for the group
        .setGroupSummary(true)
        .build();

NotificationManagerCompat notificationManager = NotificationManagerCompat.from(this);
notificationManager.notify(emailNotificationId1, newMessageNotification1);
notificationManager.notify(emailNotificationId2, newMessageNotification2);
notificationManager.notify(SUMMARY_ID, summaryNotification);

The summary notification ID should stay the same so that it is only posted once, and so you can update it later if the summary information changes (subsequent additions to the group should result in updating the existing summary).

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

Automatic grouping

On Android 7.0 (API level 24) and higher, if your app sends four or more notifications and does not specify a group key or group summary, the system might automatically group them together. Notifications grouped automatically appear with a group summary notification labeled with snippets of text from some of the grouped notifications. The user can expand this summary notification to see each individual notification, as with manually grouped notifications. Automatic grouping behavior might vary on some device types. To ensure the best experience on all devices and versions, if you know notifications should be grouped, specify a group key and group summary to ensure they are grouped.