notifications API
Hint
The notifications API is inherited from Firefox, and its primary documentation is maintained by Mozilla at MDN. Thunderbird implements only the subset of functions, events, and types listed here. The MDN pages may provide further details and examples, but they may also reference features that are not supported in Thunderbird.
Permissions
The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.
Hint
Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.
notifications
Display notifications to you.
Functions
clear(notificationId)
– [Added in TB 45]
Clears an existing notification.
Required permissions
create([notificationId], options)
– [Added in TB 45]
Creates and displays a notification.
Parameters
notificationId
Identifier of the notification. If it is empty, this method generates an id. If it matches an existing notification, this method first clears that notification before proceeding with the create operation.
options
Contents of the notification.
Return type (Promise)
_returns
The notification id (either supplied or generated) that represents the created notification.
Required permissions
getAll()
– [Added in TB 45]
Retrieves all the notifications.
Required permissions
getPermissionLevel()
Retrieves whether the user has enabled notifications from this app or extension.
Required permissions
Events
onClicked
– [Added in TB 47]
Fired when the user clicked in a non-button area of the notification.
Parameters for onClicked.addListener(listener)
listener(notificationId)
A function that will be called when this event occurs.
Parameters passed to the listener function
notificationId
The notificationId of the clicked notification.
Required permissions
onClosed
– [Added in TB 45]
Fired when the notification closed, either by the system or by user action.
Parameters for onClosed.addListener(listener)
listener(notificationId, byUser)
A function that will be called when this event occurs.
Parameters passed to the listener function
notificationId
The notificationId of the closed notification.
byUser
True if the notification was closed by the user.
Required permissions
onPermissionLevelChanged
Fired when the user changes the permission level.
Parameters for onPermissionLevelChanged.addListener(listener)
listener(level)
A function that will be called when this event occurs.
Parameters passed to the listener function
level
The new permission level.
Required permissions
onShown
– [Added in TB 56]
Fired when the notification is shown.
Parameters for onShown.addListener(listener)
listener(notificationId)
A function that will be called when this event occurs.
Parameters passed to the listener function
notificationId
The notificationId of the shown notification.
Required permissions
onShowSettings
Fired when the user clicked on a link for the app’s notification settings.
Parameters for onShowSettings.addListener(listener)
listener()
A function that will be called when this event occurs.
Required permissions
Types
CreateNotificationOptions
object
message
Main notification content.
title
Title of the notification (e.g. sender name for email).
type
Which type of notification to display.
appIconMaskUrl
A URL to the app icon mask.
buttons
Text and icons for up to two notification action buttons.
contextMessage
Alternate notification content with a lower-weight font.
eventTime
A timestamp associated with the notification, in milliseconds past the epoch.
iconUrl
A URL to the sender’s avatar, app icon, or a thumbnail for image notifications.
imageUrl
A URL to the image thumbnail for image-type notifications.
isClickable
Whether to show UI indicating that the app will visibly respond to clicks on the body of a notification.
items
Items for multi-item notifications.
priority
Priority ranges from -2 to 2. -2 is lowest priority. 2 is highest. Zero is default.
progress
Current progress ranges from 0 to 100.
NotificationItem
PermissionLevel
TemplateType
– [Added in TB 45]
Note
Only the ‘basic’ type is supported.
UpdateNotificationOptions
object
appIconMaskUrl
A URL to the app icon mask.
buttons
Text and icons for up to two notification action buttons.
contextMessage
Alternate notification content with a lower-weight font.
eventTime
A timestamp associated with the notification, in milliseconds past the epoch.
iconUrl
A URL to the sender’s avatar, app icon, or a thumbnail for image notifications.
imageUrl
A URL to the image thumbnail for image-type notifications.
isClickable
Whether to show UI indicating that the app will visibly respond to clicks on the body of a notification.
items
Items for multi-item notifications.
message
Main notification content.
priority
Priority ranges from -2 to 2. -2 is lowest priority. 2 is highest. Zero is default.
progress
Current progress ranges from 0 to 100.
title
Title of the notification (e.g. sender name for email).
type
Which type of notification to display.