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

notifications

Display notifications to you.

Note

The permission notifications is required to use messenger.notifications.*.

Functions

clear(notificationId)

– [Added in TB 45]

Clears an existing notification.

Parameters

notificationId

notificationId

(string)

The id of the notification to be updated.

Return type (Promise)

_returns

boolean

Indicates whether a matching notification existed.

Required permissions

  • notifications

create([notificationId], options)

– [Added in TB 45]

Creates and displays a notification.

Parameters

notificationId

[notificationId]

(string, optional)

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

string

The notification id (either supplied or generated) that represents the created notification.

Required permissions

  • notifications

getAll()

– [Added in TB 45]

Retrieves all the notifications.

Return type (Promise)

_returns

object

The set of notifications currently in the system.

Required permissions

  • notifications

getPermissionLevel()

Retrieves whether the user has enabled notifications from this app or extension.

Return type (Promise)

_returns

The current permission level.

Required permissions

  • notifications

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)

listener(notificationId)

A function that will be called when this event occurs.

Parameters passed to the listener function

notificationId

notificationId

(string)

The notificationId of the clicked notification.

Required permissions

  • notifications

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)

listener(notificationId, byUser)

A function that will be called when this event occurs.

Parameters passed to the listener function

notificationId

notificationId

(string)

The notificationId of the closed notification.

byUser

byUser

(boolean)

True if the notification was closed by the user.

Required permissions

  • notifications

onPermissionLevelChanged

Fired when the user changes the permission level.

Parameters for onPermissionLevelChanged.addListener(listener)

listener(level)

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

  • notifications

onShown

– [Added in TB 56]

Fired when the notification is shown.

Parameters for onShown.addListener(listener)

listener(notificationId)

listener(notificationId)

A function that will be called when this event occurs.

Parameters passed to the listener function

notificationId

notificationId

(string)

The notificationId of the shown notification.

Required permissions

  • notifications

onShowSettings

Fired when the user clicked on a link for the app’s notification settings.

Parameters for onShowSettings.addListener(listener)

listener()

listener()

A function that will be called when this event occurs.

Required permissions

  • notifications

Types

CreateNotificationOptions

object

message

message

(string)

Main notification content.

title

title

(string)

Title of the notification (e.g. sender name for email).

type

type

Which type of notification to display.

appIconMaskUrl

[appIconMaskUrl]

(string, optional)

A URL to the app icon mask.

buttons

[buttons]

(array of object, optional) Unsupported.

Text and icons for up to two notification action buttons.

contextMessage

[contextMessage]

(string, optional)

Alternate notification content with a lower-weight font.

eventTime

[eventTime]

(number, optional)

A timestamp associated with the notification, in milliseconds past the epoch.

iconUrl

[iconUrl]

(string, optional)

A URL to the sender’s avatar, app icon, or a thumbnail for image notifications.

imageUrl

[imageUrl]

(string, optional)

A URL to the image thumbnail for image-type notifications.

isClickable

[isClickable]

(boolean, optional)

Whether to show UI indicating that the app will visibly respond to clicks on the body of a notification.

items

[items]

(array of NotificationItem, optional)

Items for multi-item notifications.

priority

[priority]

(integer, optional)

Priority ranges from -2 to 2. -2 is lowest priority. 2 is highest. Zero is default.

progress

[progress]

(integer, optional)

Current progress ranges from 0 to 100.

NotificationItem

object

message

message

(string)

Additional details about this item.

title

title

(string)

Title of one item of a list notification.

PermissionLevel

string

Supported values:

denied

denied

granted

granted

TemplateType

– [Added in TB 45]

Note

Only the ‘basic’ type is supported.

string

Supported values:

basic

basic

image

image

list

list

progress

progress

UpdateNotificationOptions

object

appIconMaskUrl

[appIconMaskUrl]

(string, optional)

A URL to the app icon mask.

buttons

[buttons]

(array of object, optional) Unsupported.

Text and icons for up to two notification action buttons.

contextMessage

[contextMessage]

(string, optional)

Alternate notification content with a lower-weight font.

eventTime

[eventTime]

(number, optional)

A timestamp associated with the notification, in milliseconds past the epoch.

iconUrl

[iconUrl]

(string, optional)

A URL to the sender’s avatar, app icon, or a thumbnail for image notifications.

imageUrl

[imageUrl]

(string, optional)

A URL to the image thumbnail for image-type notifications.

isClickable

[isClickable]

(boolean, optional)

Whether to show UI indicating that the app will visibly respond to clicks on the body of a notification.

items

[items]

(array of NotificationItem, optional)

Items for multi-item notifications.

message

[message]

(string, optional)

Main notification content.

priority

[priority]

(integer, optional)

Priority ranges from -2 to 2. -2 is lowest priority. 2 is highest. Zero is default.

progress

[progress]

(integer, optional)

Current progress ranges from 0 to 100.

title

[title]

(string, optional)

Title of the notification (e.g. sender name for email).

type

[type]

(TemplateType, optional)

Which type of notification to display.