Desktop Notifications Specification

This is a draft standard for a desktop notifications service, through which applications can generate passive popups to notify the user in an asynchronous manner of events.

This specification explicitly does not include other types of notification presentation such as modal message boxes, window manager decorations or window list annotations.

Example use cases include:

In order to ensure that multiple notifications can easily be displayed at once, and to provide a convenient implementation, all notifications are controlled by a single session-scoped service which exposes a D-BUS interface.

On startup, a conforming implementation should take the org.freedesktop.Notifications service on the session bus. This service will be referred to as the "notification server" or just "the server" in this document. It can optionally be activated automatically by the bus process, however this is not required and notification server clients must not assume that it is available.

The server should implement the org.freedesktop.Notifications interface on an object with the path "/org/freedesktop/Notifications". This is the only interface required by this version of the specification.

A notification has the following components:

Each notification displayed is allocated a unique ID by the server. This is unique within the session. While the notification server is running, the ID will not be recycled unless the capacity of a uint32 is exceeded.

This can be used to hide the notification before the expiration timeout is reached. It can also be used to atomically replace the notification with another. This allows you to (for instance) modify the contents of a notification while it's on-screen.

Clients should try and avoid making assumptions about the presentation and abilities of the notification server. The message content is the most important thing.

Clients can check with the server what capabilities are supported using the GetCapabilities message. See Protocol.

If a client requires a response from a passive popup, it should be coded such that a non-focus-stealing message box can be used in the case that the notification server does not support this feature.

Body text may contain markup. The markup is XML-based, and consists of a small subset of HTML along with a few additional tags.

The following tags should be supported by the notification server. Though it is optional, it is recommended. Notification servers that do not support these tags should filter them out.

A full-blown HTML implementation is not required of this spec, and notifications should never take advantage of tags that are not listed above. As notifications are not a substitute for web browsers or complex dialogs, advanced layout is not necessary, and may in fact limit the number of systems that notification services can run on, due to memory usage and screen space. Such examples are PDAs, certain cell phones, and slow PCs or laptops with little memory.

For the same reason, a full XML or XHTML implementation using XSLT or CSS stylesheets is not part of this specification. Information that must be presented in a more complex form should use an application-specific dialog, a web browser, or some other display mechanism.

The tags specified above mark up the content in a way that allows them to be stripped out on some implementations without impacting the actual content.

A notification can optionally have an associated icon and/or image.

The icon is defined by the "app_icon" parameter. The image can be defined by the "image-path", the "image-data" hint or the deprecated "icon_data" hint.

Notifications can optionally have a type indicator. Although neither client or nor server must support this, some may choose to. Those servers implementing categories may use them to intelligently display the notification in a certain way, or group notifications of similar types.

Categories are in class.specific form. class specifies the generic type of notification, and specific specifies the more specific type of notification.

If a specific type of notification does not exist for your notification, but the generic kind does, a notification of type class is acceptable.

Third parties, when defining their own categories, should discuss the possibility of standardizing on the hint with other parties, preferably in a place such as the xdg mailing list at freedesktop.org. If it warrants a standard, it will be added to the table above. If no consensus is reached, the category should be in the form of "x-vendor.class.name."

The following table lists standard notifications as defined by this spec. More will be added in time.

Notifications have an urgency level associated with them. This defines the importance of the notification. For example, "Joe Bob signed on" would be a low urgency. "You have new mail" or "A USB device was unplugged" would be a normal urgency. "Your computer is on fire" would be a critical urgency.

Urgency levels are defined as follows:

Developers must use their own judgement when deciding the urgency of a notification. Typically, if the majority of programs are using the same level for a specific type of urgency, other applications should follow them.

For low and normal urgencies, server implementations may display the notifications how they choose. They should, however, have a sane expiration timeout dependent on the urgency level.

Critical notifications should not automatically expire, as they are things that the user will most likely want to know about. They should only be closed when the user dismisses them, for example, by clicking on the notification.

Hints are a way to provide extra data to a notification server that the server may be able to make use of.

Neither clients nor notification servers are required to support any hints. Both sides should assume that hints are not passed, and should ignore any hints they do not understand.

Third parties, when defining their own hints, should discuss the possibility of standardizing on the hint with other parties, preferably in a place such as the xdg mailing list at freedesktop.org. If it warrants a standard, it will be added to the table above. If no consensus is reached, the hint name should be in the form of "x-vendor-name."

The value type for the hint dictionary in D-BUS is of the DBUS_TYPE_VARIANT container type. This allows different data types (string, integer, boolean, etc.) to be used for hints. When adding a dictionary of hints, this type must be used, rather than putting the actual hint value in as the dictionary value.

The following table lists the standard hints as defined by this specification. Future hints may be proposed and added to this list over time. Once again, implementations are not required to support these.

The following messages must be supported by all implementations.