Skip to main content

NotificationChannel

Android notification channel grouping notifications with shared behavior.

Pass it as AndroidOptions.channel to create the channel when a notification is first posted to it, or create it upfront with Notifications.create_channel and pass its id instead. Users manage channel preferences independently in Android settings. Sound, vibration, lights, and importance cannot be reset by posting another notification or recreating the same channel; use a new ID for a different configuration.

Note

Channels exist on Android 8.0+. On earlier versions, the channel's sound, vibration, lights, and importance apply to each notification posted with it.

Raises:

  • ValueError - If id or name is empty.

Properties

  • audio_attributes_usage - Intended use of the channel's sound.
  • bypass_dnd - Whether the channel should attempt to bypass Do Not Disturb.
  • description - User-visible explanation of the notifications delivered through this channel.
  • enable_lights - Whether to use the notification LED on supported devices.
  • enable_vibration - Whether notifications in the channel vibrate.
  • group_id - ID of the notification-channel group containing this channel.
  • id - Nonempty, stable channel identifier used when posting notifications.
  • importance - Initial channel importance.
  • led_color - LED color used when enable_lights is enabled.
  • name - Nonempty, user-visible channel name displayed in Android settings.
  • play_sound - Whether notifications in the channel play sound.
  • show_badge - Whether notifications may contribute launcher badges.
  • sound - Sound resource name or content:// / file:// URI on the Android device.
  • vibration_pattern - Alternating delay and vibration durations, in milliseconds.

Properties​

audio_attributes_usageclass-attributeinstance-attribute​

audio_attributes_usage: AndroidAudioAttributesUsage = (
    AndroidAudioAttributesUsage.NOTIFICATION
)

Intended use of the channel's sound.

Helps Android select audio routing, volume, and interruption policies. It does not enable sound when play_sound is False or grant access to bypass Do Not Disturb.

Note

Fixed at channel creation.

bypass_dndclass-attributeinstance-attribute​

bypass_dnd: bool = False

Whether the channel should attempt to bypass Do Not Disturb.

Note

Obtain notification-policy access with Notifications.request_notification_policy_access before creating the channel; otherwise Android ignores the request. Bypassing Do Not Disturb doesn't override the device's silent or vibrate mode.

descriptionclass-attributeinstance-attribute​

description: str | None = None

User-visible explanation of the notifications delivered through this channel.

None shows no description.

enable_lightsclass-attributeinstance-attribute​

enable_lights: bool = False

Whether to use the notification LED on supported devices.

Note

Fixed at channel creation.

enable_vibrationclass-attributeinstance-attribute​

enable_vibration: bool = True

Whether notifications in the channel vibrate.

Note

Requires the Android VIBRATE permission. Fixed at channel creation.

group_idclass-attributeinstance-attribute​

group_id: str | None = None

ID of the notification-channel group containing this channel.

Create the group first with Notifications.create_channel_group. This organizes channels in settings; it does not group notifications in the tray.

idinstance-attribute​

id: str

Nonempty, stable channel identifier used when posting notifications.

importanceclass-attributeinstance-attribute​

importance: AndroidImportance = AndroidImportance.DEFAULT

Initial channel importance.

The user can change it after creation. See AndroidImportance for the interruption behavior of each level.

led_colorclass-attributeinstance-attribute​

led_color: ColorValue | None = None

LED color used when enable_lights is enabled.

Note

Accepts concrete Flet color names and hexadecimal colors. Theme-dependent colors cannot be resolved by this headless service. Fixed at channel creation.

nameinstance-attribute​

name: str

Nonempty, user-visible channel name displayed in Android settings.

play_soundclass-attributeinstance-attribute​

play_sound: bool = True

Whether notifications in the channel play sound.

Note

Fixed at channel creation. Use sound to choose a custom sound.

show_badgeclass-attributeinstance-attribute​

show_badge: bool = True

Whether notifications may contribute launcher badges.

Note

Requires support from the launcher and is subject to user settings.

soundclass-attributeinstance-attribute​

sound: str | None = None

Sound resource name or content:// / file:// URI on the Android device.

A raw resource name, such as "alert", refers to a file in the app's res/raw resources and omits the file extension. Add the file with the res_dir build setting, for example as raw/alert.mp3.

Note

Requires play_sound. None uses the default notification sound. Fixed at channel creation; changing this value does not replace an existing channel's sound.

A file:// URI of a file in the app's private storage is stored but not played, because the system cannot read the file.

vibration_patternclass-attributeinstance-attribute​

vibration_pattern: list[int] | None = None

Alternating delay and vibration durations, in milliseconds.

Note

For example, [0, 200, 100, 200] starts immediately and vibrates twice. Requires enable_vibration; fixed at channel creation.