# Notification channels

Android 8.0 introduces [Notification Channels](https://developer.android.com/preview/features/notification-channels.html). Any application targeting the API Level 26 or higher is **required** to add support to notification channels, or its notifications will **not** be displayed.

Fortunately, Batch comes with full builtin support for them: The SDK will register a default channel for your notifications, but many APIs are available to carefully configure it to send the right notification to the right channel.

The main feature of channels is that users will be presented with options to control them, rather than toggling all of the app's notifications. That way, you'll be able to reduce your opt-out rate by segmenting your notifications. Here's how the system UI looks like:

![Notification Channels System UI](https://38998153-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCL8wF0y1T2vLnm3yR2MW%2Fuploads%2FgnM4UN4FSwWC7g0YiALQ%2Fandroid_channels_screenshot.png?alt=media\&token=f991fd04-2dd2-4d02-bb7e-ce4f2caa52e3)

For each channel, users can change various settings, such as:

* Importance
* Vibration
* Sound

Once used, an application cannot change a channel's setting anymore, letting the user retain full control on them. This also means that these settings cannot be controller on a per-notification basis anymore, or from your own App's UI: `Batch.Push.setNotificationsType()` is affected by this, as any flag other than `ALERT` will be ignored on API 26+ devices.

### Default settings

The default behaviour is to register a channel named "Notifications", which ID is defined by `BatchNotificationChannelsManager.DEFAULT_CHANNEL_ID`.

### Changing the channel that Batch uses to display notifications

Currently, there are two ways of doing this:

* By overriding the default channel for every notification

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
Batch.Push.getChannelsManager().setChannelIdOverride("MY_CHANNEL")
```

{% endtab %}

{% tab title="Java" %}

```java
Batch.Push.getChannelsManager().setChannelIdOverride("MY_CHANNEL");
```

{% endtab %}
{% endtabs %}

* Or by providing an interceptor: Batch will call it before displaying any notification, giving you a chance to override (or not) the channel ID according to the content.

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
Batch.Push.getChannelsManager().setChannelIdInterceptor(
    NotificationChannelIdInterceptor { payload, deductedChannelId -> 
        // custom payload: {"high_importance":"true"}
        if ("true".equals(
                payload.pushBundle.getString("high_importance"),
                ignoreCase = true
            )
        ) {
            return@NotificationChannelIdInterceptor "IMPORTANT_CHANNEL"
        }
        deductedChannelId
    })
```

{% endtab %}

{% tab title="Java" %}

```java
Batch.Push.getChannelsManager().setChannelIdInterceptor(new BatchNotificationChannelsManager.NotificationChannelIdInterceptor() {
	@Nullable
	@Override
	public String getChannelId(@NonNull BatchPushPayload payload, String deductedChannelId) {
		// custom payload: {"high_importance":"true"}
		if ("true".equalsIgnoreCase(payload.getPushBundle().getString("high_importance"))) {
			return "IMPORTANT_CHANNEL";
		}
		return deductedChannelId;
	}
});
```

{% endtab %}
{% endtabs %}

These two ways to change the channel ID are not mutually exclusive: you can use both at once.

{% hint style="info" %}
Batch will not try to register these channels. If you override the channel ID, it becomes your responsibility to manage it.
{% endhint %}

### Keep the default channel ID, but change the translation

If you register your own channels, but would like to keep Batch's default fallback, you can still rename the user-facing channel name.

You can give Batch an implementation of the `BatchNotificationChannelsManager.ChannelNameProvider` interface, which will be called when Batch registers its channel with Android.

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
Batch.Push.getChannelsManager().setChannelNameProvider { 
    "Marketing notifications" 
}
```

{% endtab %}

{% tab title="Java" %}

```java
Batch.Push.getChannelsManager().setChannelNameProvider(new BatchNotificationChannelsManager.ChannelNameProvider() {
	@NonNull
	@Override
	public String getDefaultChannelName() {
		return "Marketing notifications";
	}
});
```

{% endtab %}
{% endtabs %}

If your string is in an Android string resource, you can use a builtin provider. Batch will fetch the right translation from the resource automatically:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
Batch.Push.getChannelsManager().setChannelName(context, R.string.default_channel_name)
```

{% endtab %}

{% tab title="Java" %}

```java
Batch.Push.getChannelsManager().setChannelName(context, R.string.default_channel_name);
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Like other global Batch configuration methods, these should be called in your Application's onCreate. Since this user-facing string is localized, your provider might be called on locale change.
{% endhint %}

### Directing the users to the system settings

Since your app can't change any channels settings, you might want to show a button redirecting them to these settings, if you detect that they disabled the notifications.

Batch simplifies that for you:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
// Opens Batch's channels settings
// Note: that will only work if Batch showed a notification once: the default channel is not registered beforehand. You should check if that channel has been registered beforehand.
var success = BatchNotificationChannelsManager.openSystemChannelSettings(context)

// Open the system settings for a given channel ID
success = BatchNotificationChannelsManager.openSystemChannelSettings(context, "MY_CHANNEL")
```

{% endtab %}

{% tab title="Java" %}

```java
// Opens Batch's channels settings
// Note: that will only work if Batch showed a notification once: the default channel is not registered beforehand. You should check if that channel has been registered beforehand.
boolean success = BatchNotificationChannelsManager.openSystemChannelSettings(context);

// Open the system settings for a given channel ID
success = BatchNotificationChannelsManager.openSystemChannelSettings(context, "MY_CHANNEL");
```

{% endtab %}
{% endtabs %}

### Custom receivers

If you're using a custom implementation of the Notification Builder in your own receiver, you will have to register your own channel, and set it in your notifications.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.batch.com/developer/sdk/android/advanced/notification-channels.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.