Setup

We support the following providers:

• Firebase Cloud Messaging
• Huawei Push Kit
• Xiaomi Mi Push

We ship an individual artifact for each of these to make client-side integration with their service quick and simple. See their individual documentation pages linked above for details.

Basic Setup

To enable push notifications, you need to configure the NotificationConfig with the required PushDeviceGenerator for your chosen provider. The PushDeviceGenerator is essential for registering your device with the push notification service.

Required configuration:

• pushNotificationsEnabled: Set to true to enable push notifications (enabled by default)
• pushDeviceGenerators: List of generators for your chosen push notification provider

val notificationConfig = NotificationConfig(
    pushNotificationsEnabled = true, // Enable push notifications
    pushDeviceGenerators = listOf(
        // Add your desired push device generators here
        // You can include multiple generators based on your needs
        FirebasePushDeviceGenerator(),
    ),
)

ChatClient.Builder("api-key", context)
    .notifications(notificationConfig, notificationHandler)
    .build()

boolean pushNotificationEnabled = true;
List<PushDeviceGenerator> pushDeviceGeneratorList = new ArrayList<>();
NotificationConfig notificationConfig = new NotificationConfig(pushNotificationEnabled, pushDeviceGeneratorList);

new ChatClient.Builder("api-key", context)
        .notifications(notificationConfig, notificationHandler)
        .build();

Customizing Push Notifications

If you want, you can also customize how the push notifications work.

You can customize push notifications in the following ways:

• Overriding resources: Simple customization of the notification’s icon and text resources
• NotificationHandlerFactory: Uses default styling, but provides high-level customization options
• Custom NotificationHandler: Allows to fully customize how notifications are shown and dismissed
• NotificationConfig: General, non-UI related configuration

Overriding resources

You can provide custom icon and text resources displayed in notifications by overriding them:

• We are using stream_ic_notification.xml drawable as the default notification’s icon
• Text resources are placed inside strings.xml file

Using NotificationHandlerFactory

The NotificationHandlerFactory provides a way to create a default implementation of NotificationHandler based on the Android API Level and lets you customize various top-level aspects of push notifications without the need to implement the entire NotificationHandler interface.

Customizing the notification click intent

You can customize the intent that is triggered when a user clicks on a notification by providing a lambda function to the newMessageIntent parameter of the createNotificationHandler method:

val notificationHandler = NotificationHandlerFactory.createNotificationHandler(
    context = context,
    notificationConfig = notificationConfig,
    newMessageIntent = { message: Message, channel: Channel ->
        // Return the intent you want to be triggered when the notification is clicked
        val intent: Intent = [....]
        intent
    }
)

ChatClient.Builder("api-key", context)
    .notifications(notificationConfig, notificationHandler)
    .build()

boolean pushNotificationEnabled = true;
List<PushDeviceGenerator> pushDeviceGeneratorList = new ArrayList<>();
NotificationConfig notificationConfig = new NotificationConfig(pushNotificationEnabled, pushDeviceGeneratorList);

NotificationHandler notificationHandler = NotificationHandlerFactory.createNotificationHandler(context, notificationConfig, (message, channel) -> {
    // Return the intent you want to be triggered when the notification is clicked
    Intent intent = new Intent();

    return intent;
});

new ChatClient.Builder("api-key", context)
        .notifications(notificationConfig, notificationHandler)
        .build();

Customizing the notification channel

The SDK creates a default NotificationChannel during its initialization if push notifications are enabled client-side. You can customize this channel by providing a lambda function to the notificationChannel parameter of the createNotificationHandler method:

val notificationHandler = NotificationHandlerFactory.createNotificationHandler(
    // Other setup...
    notificationChannel = {
        NotificationChannel("channel-id", "Chat Messages", NotificationManager.IMPORTANCE_DEFAULT)
    },
)

Customizing the sender icon

You can customize how the sender icon is displayed in the notification by providing a custom UserIconBuilder implementation to the userIconBuilder parameter of the createNotificationHandler method:

val notificationHandler = NotificationHandlerFactory.createNotificationHandler(
    // Other setup...
    userIconBuilder = object : UserIconBuilder {
        override suspend fun buildIcon(user: User): IconCompat? {
            // Your implementation to build an IconCompat from the User object
        }
    },
)

Customizing the notification text

You can customize the text displayed in the notification by providing a custom lambda for the notificationTextFormatter parameter of the createNotificationHandler method:

val notificationHandler = NotificationHandlerFactory.createNotificationHandler(
    // Other setup
    notificationTextFormatter = { currentUser: User?, message: Message ->
        // Your implementation to format the notification text, ex:
        "${message.user.name}: ${message.text}"
    },
)

Customizing the notification actions

By default, the notifications include action buttons for replying to the message and marking it as read. You can customize these actions by providing a custom lambda for the actionsProvider parameter of the createNotificationHandler method:

val notificationHandler = NotificationHandlerFactory.createNotificationHandler(
    // Other setup
    actionsProvider = { notificationId: Int, channel: Channel, message: Message ->
        // Your implementation to provide actions for the notification
    },
)

To retrieve/customize the default actions, you can use the NotificationActionsFactory class. It provides two methods:

• createReplyAction: Creates a reply action for the notification
• createMarkReadAction: Creates a mark as read action for the notification

val notificationHandler = NotificationHandlerFactory.createNotificationHandler(
    // Other setup
    actionsProvider = { notificationId: Int, channel: Channel, message: Message ->
        val customReply = NotificationActionsFactory.createReplyAction(
            context = context,
            notificationId = notificationId,
            channel = channel,
            // Custom title and input hint
            title = "Reply now",
            hint = "Write a message to ${channel.name}",
        )
        val customMarkRead = NotificationActionsFactory.createMarkReadAction(
            context = context,
            notificationId = notificationId,
            channel = channel,
            message = message,
            // Custom title
            title = "Already seen",
        )
        listOf(customMarkRead, customReply)
    },
)

Transforming the notification before showing it

Instead of fully customizing the notification display logic, you can transform the notification after it was created by the SDK, but before it is shown to the user. You can do this by providing a custom lambda for the notificationBuilderTransformer parameter of the createNotificationHandler:

val notificationHandler = NotificationHandlerFactory.createNotificationHandler(
    // Other setup
    notificationBuilderTransformer = { builder: NotificationCompat.Builder, notification: ChatNotification ->
        // Your implementation to transform the notification builder
        builder
    },
)

Controlling whether the push message should be shown or not

You can control whether push notifications should be processed when received. You can define this behavior by providing a custom lambda for the onPushMessage parameter of the createNotificationHandler method. You can also use this callback to perform any side effects when a push message is received. By default, the SDK handles all push messages internally.

val notificationHandler = NotificationHandlerFactory.createNotificationHandler(
    // Other setup
    onPushMessage = { message: PushMessage ->
        // Your implementation to determine whether to show the notification
        // Return true to handle the message yourself, false to let the SDK handle it internally
        true // or false
    },
)

Custom NotificationHandler

The SDK allows you to fully override how the incoming push notifications are handled. To do this, implement the NotificationHandler interface and show your own notification. If you want to dismiss notifications when a user visits a channel or logs off of the app, you will need to implement methods for dismissing notifications on the NotificationHandler class.

The NotificationHandler interface provides several methods to handle different types of events:

• onChatEvent(event: NewMessageEvent): Handles WebSocket events for new messages when the user is connected. This method is only invoked when the user has an active WebSocket connection. You can use this to control whether to show notifications while the user is active in the app. Return true to handle the event yourself, false to let the SDK handle it internally.
• onNotificationReminderDueEvent(event: NotificationReminderDueEvent): Handles WebSocket events for reminder notifications when the user is connected. This method is only invoked when the user has an active WebSocket connection. Return true to handle the event yourself, false to let the SDK handle it internally.
• onPushMessage(message: PushMessage): Acts as a bypass to control whether push notifications should be processed when received. Return true to handle the push message yourself, false to let the SDK handle it internally.
• showNotification(notification: ChatNotification): Shows notifications for different types of notifications. Supported types are: MessageNew, MessageUpdated, ReactionNew and NotificationReminderDue.
• dismissChannelNotifications(channelType: String, channelId: String): Dismisses all notifications for a specific channel.
• dismissAllNotifications(): Dismisses all notifications.
• onNotificationPermissionStatus(status: NotificationPermissionStatus): Handles notification permission lifecycle.

class MyNotificationHandler(private val context: Context) : NotificationHandler {
    private val notificationManager: NotificationManager by lazy {
        context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
    }

    override fun onNotificationPermissionStatus(status: NotificationPermissionStatus) {
        when (status) {
            NotificationPermissionStatus.REQUESTED -> {
                // invoked when POST_NOTIFICATIONS permission is requested
            }
            NotificationPermissionStatus.GRANTED -> {
                // invoked when POST_NOTIFICATIONS permission is granted
            }
            NotificationPermissionStatus.DENIED -> {
                // invoked when POST_NOTIFICATIONS permission is denied
            }
            NotificationPermissionStatus.RATIONALE_NEEDED -> {
                // invoked when POST_NOTIFICATIONS permission requires rationale
            }
        }
    }

    override fun showNotification(notification: ChatNotification) {
        when (notification) {
            is ChatNotification.MessageNew -> {
                // Handle new message notification
                // You can customize the notification here
            }
            is ChatNotification.ReactionNew -> {
                // Handle new reaction notification
                // You can customize the notification here
            }
            is ChatNotification.MessageUpdated -> {
                // Handle message updated notification
                // You can customize the notification here
            }
            is ChatNotification.NotificationReminderDue -> {
                // Handle reminder notification
                // You can customize the notification here
            }
        }
    }

    override fun dismissChannelNotifications(channelType: String, channelId: String) {
        // Dismiss all notification related with this channel
    }

    override fun dismissAllNotifications() {
        // Dismiss all notifications
    }
}

class MyNotificationHandler implements NotificationHandler {

    NotificationManager notificationManager;

    public MyNotificationHandler(Context context) {
        notificationManager = (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE) ;
    }

    @Override
    public void onNotificationPermissionStatus(@NonNull NotificationPermissionStatus status) {
        switch (status) {
            case REQUESTED:
                // invoked when POST_NOTIFICATIONS permission is requested
                break;
            case GRANTED:
                // invoked when POST_NOTIFICATIONS permission is granted
                break;
            case DENIED:
                // invoked when POST_NOTIFICATIONS permission is denied
                break;
            case RATIONALE_NEEDED:
                // invoked when POST_NOTIFICATIONS permission requires rationale
                break;
        }
    }

    @Override
    public void showNotification(@NonNull ChatNotification notification) {
        if (notification instanceof ChatNotification.MessageNew) {
            ChatNotification.MessageNew messageNew = (ChatNotification.MessageNew) notification;
            // Handle new message notification
            // You can customize the notification here
        } else if (notification instanceof ChatNotification.ReactionNew) {
            ChatNotification.ReactionNew reactionNew = (ChatNotification.ReactionNew) notification;
            // Handle new reaction notification
            // You can customize the notification here
        } else if (notification instanceof ChatNotification.MessageUpdated) {
            ChatNotification.MessageUpdated messageUpdated = (ChatNotification.MessageUpdated) notification;
            // Handle message updated notification
            // You can customize the notification here
        } else if (notification instanceof ChatNotification.NotificationReminderDue) {
            ChatNotification.NotificationReminderDue reminderDue = (ChatNotification.NotificationReminderDue) notification;
            // Handle reminder notification
            // You can customize the notification here
        }
    }

    @Override
    public void dismissChannelNotifications(@NonNull String channelType, @NonNull String channelId) {
        // Dismiss all notification related with this channel
    }

    @Override
    public void dismissAllNotifications() {
        // Dismiss all notifications
    }
}

Finally, pass as the NotificationHandler implementation to the ChatClient.Builder when initializing the Stream Android SDK:

val notificationHandler = MyNotificationHandler(context)

ChatClient.Builder("api-key", context)
    .notifications(notificationConfig, notificationHandler)
    .build()

NotificationHandler notificationHandler = new MyNotificationHandler(context);

new ChatClient.Builder("api-key", context)
    .notifications(notificationConfig, notificationHandler)
    .build();

Using NotificationConfig

The NotificationConfig class provides comprehensive control over push notification behavior. Here’s a detailed explanation of each property:

WebSocket Connection Behavior

ignorePushMessageWhenUserOnline: (type: String) -> Boolean Controls whether push notifications should be shown when the user has an active WebSocket connection. This allows you to customize behavior based on notification type.

Supported notification types:

• ChatNotification.TYPE_MESSAGE_NEW - New message notifications
• ChatNotification.TYPE_MESSAGE_UPDATED - Message updated notifications
• ChatNotification.TYPE_REACTION_NEW - New message reaction notifications
• ChatNotification.TYPE_NOTIFICATION_REMINDER_DUE - Reminder notifications

Default behavior:

• New message, message updated and reaction notifications are ignored when the user has an active WebSocket connection
• Reminder notifications are always shown, even when the user has an active WebSocket connection

val notificationConfig = NotificationConfig(
    ignorePushMessageWhenUserOnline = { type ->
        when (type) {
            ChatNotification.TYPE_MESSAGE_NEW -> true // Ignore new messages when online
            ChatNotification.TYPE_MESSAGE_UPDATED -> true // Ignore message updates when online
            ChatNotification.TYPE_REACTION_NEW -> true // Ignore reactions when online
            ChatNotification.TYPE_NOTIFICATION_REMINDER_DUE -> false // Always show reminders
            else -> true // Default behavior for unknown types
        }
    }
)

Runtime Notification Control

shouldShowNotificationOnPush: () -> Boolean = { true } Allows you to control whether notifications should be displayed after receiving a push message. This function is called for each push notification received and can be changed at runtime.

This is particularly useful when users want to temporarily disable notifications or when you need to implement custom logic based on your app’s internal state.

val notificationConfig = NotificationConfig(
    shouldShowNotificationOnPush = {
        // Custom logic to determine if notification should be shown
        // For example, only show notifications during certain hours
        val currentHour = Calendar.getInstance().get(Calendar.HOUR_OF_DAY)
        currentHour in 8..22 // Only show notifications between 8 AM and 10 PM
    }
)

Permission Management

requestPermissionOnAppLaunch: () -> Boolean = { true } Controls whether the SDK should automatically request the POST_NOTIFICATIONS permission when the app launches. This is particularly important for Android 13+ where notification permission is required.

val notificationConfig = NotificationConfig(
    requestPermissionOnAppLaunch = {
        // Custom logic to determine if permission should be requested
        // For example, only request on first app launch
        isFirstAppLaunch()
    }
)

Advanced Features

autoTranslationEnabled: Boolean = false Enables or disables the auto-translation feature for push notifications. When enabled, notifications will be automatically translated based on the user’s language preferences.

val notificationConfig = NotificationConfig(
    autoTranslationEnabled = true // Enable automatic translation
)

Complete Configuration Example

Here’s a complete example showing how to configure all properties:

val notificationConfig = NotificationConfig(
    // WebSocket connection behavior
    ignorePushMessageWhenUserOnline = { type ->
        when (type) {
            ChatNotification.TYPE_MESSAGE_NEW -> true
            ChatNotification.TYPE_NOTIFICATION_REMINDER_DUE -> false
            else -> true
        }
    },

    // Runtime notification control
    shouldShowNotificationOnPush = {
        val currentHour = Calendar.getInstance().get(Calendar.HOUR_OF_DAY)
        currentHour in 8..22
    },

    // Permission management
    requestPermissionOnAppLaunch = { true },

    // Advanced features
    autoTranslationEnabled = true,
)

ChatClient.Builder("api-key", context)
    .notifications(notificationConfig, notificationHandler)
    .build()

NotificationConfig notificationConfig = new NotificationConfig(
    type -> { // ignorePushMessageWhenUserOnline
        switch (type) {
            case ChatNotification.TYPE_MESSAGE_NEW:
                return true;
            case ChatNotification.TYPE_NOTIFICATION_REMINDER_DUE:
                return false;
            default:
                return true;
        }
    },
    () -> { // shouldShowNotificationOnPush
        Calendar calendar = Calendar.getInstance();
        int currentHour = calendar.get(Calendar.HOUR_OF_DAY);
        return currentHour >= 8 && currentHour <= 22;
    },
    () -> true, // requestPermissionOnAppLaunch
    false, // autoTranslationEnabled
);

new ChatClient.Builder("api-key", context)
    .notifications(notificationConfig, notificationHandler)
    .build();

Dismissing notifications

Our MessageListView UI component and MessageList Compose UI Component automatically dismiss notifications related to a Channel when the user opens it.

If you need to dismiss them manually (for example, if you are using a custom MessageListView component) you can call the ChatClient::dismissChannelNotifications method, providing the channelType and channelId from the Channel that you would like to dismiss notifications:

ChatClient.instance().dismissChannelNotifications("messaging", "general")

ChatClient.instance().dismissChannelNotifications("messaging", "general");

Notifications are also automatically dismissed when the user logs out from the SDK.

Receiving Push Notifications with expired JWT token

A common scenario with short-lived Stream JWT tokens is receiving a push notification while the app is killed, and the Stream JWT token is already expired. In this case, the SDK cannot properly invoke the TokenProvider that you would pass via the ChatClient::connectUser method, because in a common use case, you would not automatically connect the user when receiving a push notification, thus the ChatClient will not have a registered TokenProvider (yet). The SDK however, must internally fetch some data from the Stream server to properly show the notification, and for this it needs a valid JWT token. To bypass this, the NotificationConfig class provides a tokenProvider property, that you can set at the time of building the ChatClient, without the need to call connectUser. This TokenProvider will be invoked only in this specific scenario, when the ChatClient attempts to load notification data with an expired JWT token, and the app still hasn’t called connectUser.

You can set this TokenProvider as follows:

val notificationConfig = NotificationConfig(
    tokenProvider = CustomTokenProvider(),
)
ChatClient.Builder("api-key", context)
    .notifications(notificationConfig, notificationHandler)
    .build()

Unsubscribing from push notifications

If you want to permanently stop receiving push notifications on a device, you need to delete the device from the Stream backend. There are two ways to do this:

• Automatic deletion: The deletion of the device can be done automatically when the user disconnects from the SDK. This is controlled by the deleteDevice parameter of the disconnect method:

// Setting deleteDevice to true will result in the
// device being deleted from Stream backend
ChatClient.instance()
    .disconnect(deleteDevice = true)
    .enqueue()

• Manual deletion: If you want to fully control when the device is deleted, you can manually delete the device by calling ChatClient::deleteDevice, providing the device ID (push token) you used when registering the device:

val device = Device(
    token = "your_push_token", // ex. Firebase/Huawei/Xiaomi token
    pushProvider = PushNotificationsProvider.FIREBASE, // or HUAWEI, XIAOMI
    pushProviderName = "your_push_provider_name",
)
ChatClient.instance()
    .deleteDevice(device)
    .enqueue()