Create an Expandable Notification

A basic notification usually includes a title, a line of text, and one or more actions the user can perform in response. To provide even more information, you can also create large, expandable notifications by applying one of several notification templates as described on this page.

To start, build a notification with all the basic content as described in Create a Notification. Then, call setStyle() with a style object and supply information corresponding to each template, as shown below.

Add a large image

To add an image in your notification, pass an instance of NotificationCompat.BigPictureStyle to setStyle().

var notification = NotificationCompat.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.new_post)
        .setContentTitle(imageTitle)
        .setContentText(imageDescription)
        .setStyle(NotificationCompat.BigPictureStyle()
                .bigPicture(myBitmap))
        .build()

Notification notification = new NotificationCompat.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.new_post)
        .setContentTitle(imageTitle)
        .setContentText(imageDescription)
        .setStyle(new NotificationCompat.BigPictureStyle()
               .bigPicture(myBitmap))
        .build();

To make the image appear as a thumbnail only while the notification is collapsed (as shown in figure 1), call setLargeIcon() and pass it the image, but also call BigPictureStyle.bigLargeIcon() and pass it null so the large icon goes away when the notification is expanded:

var notification = NotificationCompat.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.new_post)
        .setContentTitle(imageTitle)
        .setContentText(imageDescription)
        .setLargeIcon(myBitmap)
        .setStyle(NotificationCompat.BigPictureStyle()
                .bigPicture(myBitmap)
                .bigLargeIcon(null))
        .build()

Notification notification = new NotificationCompat.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.new_post)
        .setContentTitle(imageTitle)
        .setContentText(imageDescription)
        .setLargeIcon(myBitmap)
        .setStyle(new NotificationCompat.BigPictureStyle()
                .bigPicture(myBitmap)
                .bigLargeIcon(null))
        .build();

Figure 1. A notification using NotificationCompat.BigPictureStyle

Add a large block of text

Apply NotificationCompat.BigTextStyle to display text in the expanded content area of the notification:

var notification = NotificationCompat.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.new_mail)
        .setContentTitle(emailObject.getSenderName())
        .setContentText(emailObject.getSubject())
        .setLargeIcon(emailObject.getSenderAvatar())
        .setStyle(NotificationCompat.BigTextStyle()
                .bigText(emailObject.getSubjectAndSnippet()))
        .build()

Notification notification = new NotificationCompat.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.new_mail)
        .setContentTitle(emailObject.getSenderName())
        .setContentText(emailObject.getSubject())
        .setLargeIcon(emailObject.getSenderAvatar())
        .setStyle(new NotificationCompat.BigTextStyle()
                .bigText(emailObject.getSubjectAndSnippet()))
        .build();

Figure 2. A notification using NotificationCompat.BigTextStyle

Tip: To add formatting in your text (bold, italic, line breaks, and so on), you can add styling with HTML markup.

Create an inbox-style notification

Apply NotificationCompat.InboxStyle to a notification if you want to add multiple short summary lines, such as snippets from incoming emails. This allows you to add multiple pieces of content text that are each truncated to one line, instead of one continuous line of text provided by NotificationCompat.BigTextStyle.

To add a new line, call addLine() up to 6 times. If you add more than 6 lines, only the first 6 are visible.

var notification = NotificationCompat.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.new_mail)
        .setContentTitle("5 New mails from " + sender.toString())
        .setContentText(subject)
        .setLargeIcon(aBitmap)
        .setStyle(NotificationCompat.InboxStyle()
                .addLine(messageSnippet1)
                .addLine(messageSnippet2))
        .build()

Notification notification = new NotificationCompat.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.new_mail)
        .setContentTitle("5 New mails from " + sender.toString())
        .setContentText(subject)
        .setLargeIcon(aBitmap)
        .setStyle(new NotificationCompat.InboxStyle()
                .addLine(messageSnippet1)
                .addLine(messageSnippet2))
        .build();

Tip: You can distinguish the message's subject and message in each line by adding styling with HTML markup (such as bolding the subject).

Show a conversation in a notification

Apply NotificationCompat.MessagingStyle to display sequential messages between any number of people. This is ideal for messaging apps because it provides a consistent layout for each message by handling the sender name and message text separately, and each message can be multiple lines long.

To add a new message, call addMessage(), passing the message text, the time received, and the sender name. You can also pass this information as a NotificationCompat.MessagingStyle.Message object.

var message1 = NotificationCompat.MessagingStyle.Message(messages[0].getText(),
        messages[0].getTime(),
        messages[0].getSender())
var message2 = NotificationCompat.MessagingStyle.Message(messages[1].getText(),
        messages[1].getTime(),
        messages[1].getSender())
var notification = NotificationCompat.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.new_message)
        .setStyle(NotificationCompat.MessagingStyle(resources.getString(R.string.reply_name))
                .addMessage(message1)
                .addMessage(message2))
        .build()

NotificationCompat.MessagingStyle.Message message1 =
        new NotificationCompat.MessagingStyle.Message(messages[0].getText(),
                                                      messages[0].getTime(),
                                                      messages[0].getSender());
NotificationCompat.MessagingStyle.Message message2 =
        new NotificationCompat.MessagingStyle.Message(messages[1].getText(),
                                                      messages[1].getTime(),
                                                      messages[1].getSender());

Notification notification = new NotificationCompat.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.new_message)
        .setStyle(new NotificationCompat.MessagingStyle(resources.getString(R.string.reply_name))
                .addMessage(message1)
                .addMessage(message2))
        .build();

Figure 3. A notification using NotificationCompat.MessagingStyle

Optionally, you can call setConversationTitle() to add a title that appears above the conversation. This might be the user-created name of the group or, if it doesn't have a specific name, a list of the participants in the conversation. Do not set a conversation title for one-on-one chats, because the system uses the existence of this field as a hint that the conversation is a group.

This style applies only on devices running Android 7.0 (API level 24) and up. When using the compatibility library (NotificationCompat) as demonstrated above, notifications with MessagingStyle will fallback automatically to a supported expanded notification style.

When building a notification like this for a chat conversation, you should also add a direct reply action.

Create a notification with media controls

Apply NotificationCompat.MediaStyle to display media playback controls and track information.

Call addAction() up to five times to display up to five separate icon buttons. And call setLargeIcon() to set the album artwork.

Unlike the other notification styles, MediaStyle allows you to also modify the collapsed-size content view by specifying three action buttons that should also appear in the collapsed view. To do so, provide the action button indices to setShowActionsInCompactView().

If the notification represents an active media session, also attach a MediaSession.Token to the notification using setMediaSession(). Android then identifies this as a notification representing an active media session and respond accordingly (by showing album artwork in the lock screen, for example).

import android.support.v4.app.NotificationCompat
import android.support.v4.media.app.NotificationCompat as MediaNotificationCompat

var notification = NotificationCompat.Builder(context, CHANNEL_ID)
        // Show controls on lock screen even when user hides sensitive content.
        .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
        .setSmallIcon(R.drawable.ic_stat_player)
        // Add media control buttons that invoke intents in your media service
        .addAction(R.drawable.ic_prev, "Previous", prevPendingIntent) // #0
        .addAction(R.drawable.ic_pause, "Pause", pausePendingIntent) // #1
        .addAction(R.drawable.ic_next, "Next", nextPendingIntent) // #2
        // Apply the media style template
        .setStyle(MediaNotificationCompat.MediaStyle()
                .setShowActionsInCompactView(1 /* #1: pause button \*/)
                .setMediaSession(mediaSession.getSessionToken()))
        .setContentTitle("Wonderful music")
        .setContentText("My Awesome Band")
        .setLargeIcon(albumArtBitmap)
        .build()

Notification notification = new NotificationCompat.Builder(context, CHANNEL_ID)
        // Show controls on lock screen even when user hides sensitive content.
        .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
        .setSmallIcon(R.drawable.ic_stat_player)
        // Add media control buttons that invoke intents in your media service
        .addAction(R.drawable.ic_prev, "Previous", prevPendingIntent) // #0
        .addAction(R.drawable.ic_pause, "Pause", pausePendingIntent)  // #1
        .addAction(R.drawable.ic_next, "Next", nextPendingIntent)     // #2
        // Apply the media style template
        .setStyle(new android.support.v4.media.app.Notification.MediaStyle()
                .setShowActionsInCompactView(1 /* #1: pause button */)
                .setMediaSession(mediaSession.getSessionToken()))
        .setContentTitle("Wonderful music")
        .setContentText("My Awesome Band")
        .setLargeIcon(albumArtBitmap)
        .build();

Figure 4. A notification using NotificationCompat.MediaStyle

For more information, also read Using MediaStyle notifications with a foreground service. For sample code that uses notifications, see the People sample.