Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# Notification

## Description

Portal for sending notifications

This simple interface lets sandboxed applications send and withdraw notifications. It is not possible for the application to learn if the notification was actually presented to the user. Not a portal in the strict sense, since there is no user interaction.

Note that in contrast to most other portal requests, notifications are expected to outlast the running application. If a user clicks on a notification after the application has exited, it will get activated again.

Notifications can specify actions that can be activated by the user. Actions whose name starts with ‘app.’ are assumed to be exported (without the ‘app.’ prefix) and will be activated via D-Bus Activation using `ActivateAction()` method in the `org.freedesktop.Application` interface. An activation-token for XDG Activation and an application-defined target is passed when activating the action. Other actions are activated by sending the org.freedesktop.portal.Notification::ActionInvoked signal to the application.

This documentation describes version 2 of this interface.

## Properties

### org.freedesktop.portal.Notification:SupportedOptions

    SupportedOptions readable a{sv}

Some properties in org.freedesktop.portal.Notification.AddNotification may have options advertised by the server.

Currently there are the following options the notification server can advertise:

- `category` (`as`)

  Categories that the notification server understands and supports.

- `button-purpose` (`as`)

  Button purposes that the notification server understands and supports. This is the list of options that can be used as purpose for buttons.

### org.freedesktop.portal.Notification:version

    version readable u

## Methods

### org.freedesktop.portal.Notification.AddNotification

    AddNotification (
      IN id s,
      IN notification a{sv}
    )

Sends a notification.

The ID can be used to later withdraw the notification. If the application reuses the same ID without withdrawing, the notification is updated with the new one. It’s possible to set `show-as-new` hint in the `display-hint` property to animate replacing the notification instead of updating it.

The format of the serialized notification is a vardict, with the following supported keys, all of which are optional:

- `title` (`s`)

  User-visible string to display as the title.

  This should be a short string, if it doesn’t fit the UI it may be truncated to fit on a single line.

- `body` (`s`)

  User-visible string to display as the body.

  This can be a long string but if it doesn’t fit the UI it may be wrapped or/and truncated.

- `markup-body` (`s`)

  The same as `body` but with support for markup formatting. The markup is XML-based and supports a small subset of HTML `<b>...</b>`, `<i>...</i>` and `<a href="...">...</a>`.

  Any markup not supported, e.g. new lines, will be removed from the string. In the future, the set of supported markup may be extended.

  This can be a long string but if it doesn’t fit the UI it may be wrapped or/and truncated.

- `icon` (`v`)

  A serialized icon to add to the notification. The icon must pass icon validation in order to be used. The format for serialized icon is a tuple (sv) with the following supported keys:

  - `themed` (`as`)

    A themed icon containing an array of strings with the icon names.

    This is the same format as a serialized GThemedIcon at the moment, but this interoperability may change in the future.

  - `bytes` (`ay`)

    Since version 2, this is deprecated and should not be used. Please use the themed or file-descriptor option to set an icon.

    This is the same format as a serialized GBytesIcon at the moment, but this interoperability may change in the future.

  - `file-descriptor` (`h`)

    A file descriptor to an image file in png, jpeg or svg form. The file-descriptor used needs to be sealable, currently this is only possible for file descriptors created with `memfd_create()` with the `MFD_ALLOW_SEALING` flag set.

  For historical reasons, it is also possible to send a simple string for themed icons with a single icon name.

  There may be further restrictions on the supported kinds of icons.

- `sound` (`v`)

  A serialized sound to add to the notification. Supported sound formats are ogg/opus, ogg/vorbis and wav/pcm.

  The format for serialized sound is a tuple (sv) with the following supported keys:

  - `file-descriptor` (`h`)

    A file descriptor to a sound file. The file-descriptor used needs to be sealable, currently this is only possible for file descriptors created with `memfd_create()` with the `MFD_ALLOW_SEALING` flag set.

  To play the default sound the string `default` can be passed. To play no sound at all the string `silent` can be passed. If this property isn’t specified the notification server can decide whether to play a sound.

  There may be further restrictions on the supported kinds of sounds.

- `priority` (`s`)

  The priority for the notification. Supported values:

  - `low`

  - `normal`

  - `high`

  - `urgent`

- `default-action` (`s`)

  Name of an action that is exported by the application. This action will be activated when the user clicks on the notification.

- `default-action-target` (`v`)

  Target parameter to send along when activating the default action.

- `buttons` (`aa{sv}`)

  Array of serialized buttons to add to the notification. The format for serialized buttons is a vardict with the following supported keys:

  - `label` (`s`)

    User-visible label for the button. Mandatory, if no purpose is specified. It is strongly recommended to always provide sensible label. Buttons without a `label` are ignored by the server when it doesn’t understand the `purpose` or is needed to display the button.

  - `action` (`s`)

    Name of an action that is exported by the application. The action will be activated when the user clicks on the button. Mandatory.

  - `target` (`v`)

    Target parameter to send along when activating the action.

  - `purpose` (`s`)

    The `purpose` of the button. This information may be used by the notification server to treat the button specially.

    Depending on the `purpose` other fields of the button may be ignored. If the server doesn’t understand the `purpose` it will be ignored and the button will be shown as a normal button.

    Most standardized hints are defined as part of a `category`. Additional purposes may be defined by notification servers using `x-vendor` prefix e.g. `x-gnome.class.specific`

    The following purposes are defined outside of a `category`:

    - `system.custom-alert`:

      Not a button in a strict sense. This action may be called, depending on system policies, automatically by the notification server whenever the notification is shown.

      This allows apps to use custom methods for notifying the user, for example, to play audio from a special source like a streaming service or a radio station.

      No `label` should be given when this purpose is used, so that the server can ignore the button if it doesn’t understand the purpose.

- `display-hint` (`as`)

  An array of ways to display the notification. If none are set, or the notification server has its own policy, it is free to decide how and where to display the notification.

  - `transient`

    The notification is displayed only as a banner and won’t be kept by the server in a tray.

    It’s a programmer error to specify `tray` at the same time.

  - `tray`

    No banner for the notification will be displayed and the notification is placed in the tray.

    It’s a programmer error to specify `transient` at the same time.

  - `persistent`

    Make the notification persistent in the notification tray. The user can’t dismiss it using the usual close button or gesture.

    Apps are only allowed to display persistent notifications as long as they have a window. Once the last window of an app is closed the persistent notification will be removed.

  - `hide-on-lockscreen`

    Don’t show the notification on the lockscreen.

  - `hide-content-on-lockscreen`

    All content of the notification will be hidden on the lockscreen.

  - `show-as-new`

    If a notification with the same `id` of the app exists already replace the previous notification, by removing the old notification (including animation, etc) and adding a new notification.

    If this hint isn’t specified the notification’s content is updated without any flickering.

- `category` (`s`)

  The `category` describes the content of a notification. A notification server may use this information to display the notification specially. Some categories also include button purposes that can be set for a button so that the notification can know the purpose of the button.

  Additional categories and button purposes may be defined by notification servers using `x-vendor` prefix e.g. `x-gnome.class.specific`

  The following categories are standarized so far:

  - `im.received`

    Intended for instant messaging apps displaying notifications for new messages.

    This category has the following button purposes:

    - `im.reply-with-text`:

      Inline replies for instant messaging. The user-provided text will be added to the response.

      The user response (`s`) will be placed as the second value in the parameter array of exported actions. For non-exported actions it will be placed as the third value in the parameter array of org.freedesktop.portal.Notification::ActionInvoked.

  - `alarm.ringing`

    Intended for alarm clock apps

  - `call.incoming`

    Intended for call apps to notify the user about an incoming call.

    This category has the following button purposes:

    - `call.accept`:

      Accept the incoming call.

    - `call.decline`:

      Decline the incoming call.

  - `call.ongoing`

    Intended for call apps while a call is ongoing.

    This type has the following button purposes:

    - `call.hang-up`:

      Hang up the ongoing call.

    - `call.enable-speakerphone`:

      Enable the speakerphone for the ongoing call.

    - `call.disable-speakerphone`:

      Disable the speakerphone for the ongoing call.

  - `call.unanswered`

    Intended to be used by call apps when a call was missed.

  - `weather.warning.extreme`

    Intended to be used to display an extreme weather warning.

  - `cellbroadcast.danger.extreme`

    Intended to be used to display extreme danger warnings broadcasted by the cell network.

  - `cellbroadcast.danger.severe`

    Intended to be used to display severe danger warnings broadcasted by the cell network.

  - `cellbroadcast.amber-alert`

    Intended to be used to display amber alerts broadcasted by the cell network.

  - `cellbroadcast.test`

    Intended to be used to display tests broadcasted by the cell network.

  - `os.battery.low`

    Intended to be used to indicate that the system is low on battery.

  - `browser.web-notification`

    Intended to be used by browsers to mark notifications send by websites via the Notifications API.

id

  Application-provided ID for this notification

notification

  Vardict with the serialized notification

### org.freedesktop.portal.Notification.RemoveNotification

    RemoveNotification (
      IN id s
    )

Withdraws a notification.

id

  Application-provided ID for this notification

## Signals

### org.freedesktop.portal.Notification::ActionInvoked

    ActionInvoked (
      id s,
      action s,
      parameter av
    )

Send to the application when a non-exported action is activated.

The `parameter` contains the following values in order:

1. The target for the action, if one was specified.

2. The platform-data as vardict (`a{sv}`) containing an `activation-token` (`s`) for XDG Activation

3. The user response for an action based on the purpose if applicable.

id

  the application-provided ID for the notification

action

  the name of the action

parameter

  an array containing additional information