Notifications
6.9.0The Notifications API allows you to raise notifications, handle notification and action clicks via Interop methods, control the Notification Panel and subscribe for notification events.
The Notifications API is accessible through the io.notifications object.
APIobject
Description
Notifications API.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| maxActions | number | The maximum number of notification actions that is supported. |
||
| panel | NotificationPanelAPI | API for controlling the Notification Panel. |
Methods
clearmethod
Signature
(id: string) => Promise<void>
Description
Clears a notification by ID.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | ID of the notification to clear. |
clearAllmethod
Signature
() => Promise<void>
Description
Clears all notifications.
clearManymethod
Signature
(notifications: string[]) => Promise<void>
Description
Clears multiple notifications using a list of IDs.
Available since version io.Connect Desktop 9.5
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| notifications | string[] | List of IDs of the notifications to clear. |
clearOldmethod
Signature
() => Promise<void>
Description
Clears all notifications in the Notification Panel that the user has already seen.
clickmethod
Signature
(id: string, action?: string, options?: ClickOptions) => Promise<void>
Description
Clicks programmatically a notification or a notification action.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | ID of the notification to click. |
|
| action | string | ID of the action to click. |
|
| options | ClickOptions | Options for the clicked notification. |
configuremethod
Signature
(options: Configuration) => Promise<void>
Description
Configures the global notification settings.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| options | Configuration | Global notification settings. |
getConfigurationmethod
Signature
() => Promise<Configuration>
Description
Retrieves the current global notification settings.
getFiltermethod
Signature
() => Promise<NotificationFilter>
Description
Retrieves the current filter with apps allowed or not allowed to raise notifications.
importmethod
Signature
(notificationOptions: IOConnectNotificationOptions[]) => Promise<NotificationData[]>
Description
Imports a list of notifications into the platform. Only imported notifications with state "Active" will be shown as notification toasts.
All imported notifications will be available in the Notification Panel. An event for raising a notification will be triggered for all imported notifications.
Available since version io.Connect Desktop 9.6
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| notificationOptions | IOConnectNotificationOptions[] | List of objects each describing a notification to import. The notification options for importing notifications are identical to the ones for raising a notification. |
listmethod
Signature
() => Promise<NotificationData[]>
Description
Retrieves a list of objects describing all available notifications.
onClosedmethod
Signature
(callback: (notification: { id: string; }) => void) => UnsubscribeFunction
Description
Notifies when a notification is closed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (notification: { id: string; }) => void | Callback function for handling the event. |
onConfigurationChangedmethod
Signature
(callback: (config: Configuration) => void) => UnsubscribeFunction
Description
Notifies when the global notification settings are changed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (config: Configuration) => void | Callback function for handling the event. |
onCounterChangedmethod
Signature
(callback: (info: { count: number; }) => void) => UnsubscribeFunction
Description
Notifies when the notification counter is changed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (info: { count: number; }) => void | Callback function for handling the event. |
onDataChangedmethod
Signature
<T>(callback: (notification: { id: string; }, data: T) => void) => UnsubscribeFunction
Description
Notifies when the arbitrary data associated with the notification (available in the data property of the notification) is changed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (notification: { id: string; }, data: T) => void | Callback function for handling the event. |
onRaisedmethod
Signature
(callback: (notification: NotificationData) => void) => UnsubscribeFunction
Description
Notifies when a new notification is raised.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (notification: NotificationData) => void | Callback function for handling the event. |
onStateChangedmethod
Signature
(callback: (notification: { id: string; }, state: State) => void) => UnsubscribeFunction
Description
Notifies when the state of a notification is changed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (notification: { id: string; }, state: State) => void | Callback function for handling the event. |
raisemethod
Signature
(notification: IOConnectNotificationOptions) => Promise<Notification>
Description
Raises a new notification.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| notification | IOConnectNotificationOptions | Options for the raised notification. |
setFiltermethod
Signature
(filter: NotificationFilter) => Promise<NotificationFilter>
Description
Sets a filter with apps allowed or not allowed to raise notifications.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| filter | NotificationFilter | Filter with names of apps allowed or not allowed to raise notifications. |
setStatemethod
setStatesmethod
Signature
(notifications: string[], state: State) => Promise<void>
Description
Sets multiple notifications to the same notification state.
Available since version io.Connect Desktop 9.5
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| notifications | string[] | List of IDs of the notifications whose state to set. |
|
| state | State | Value for the new notification state. |
snoozemethod
Signature
(id: string, duration: number) => Promise<void>
Description
Snoozes a notification.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | ID of the notification to snooze. |
|
| duration | number | Interval in milliseconds for which to snooze the notification. |
snoozeManymethod
Signature
(notifications: string[], duration: number) => Promise<void>
Description
Snoozes multiple notifications for the same duration.
Available since version io.Connect Desktop 9.5
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| notifications | string[] | List of IDs of the notifications to snooze. |
|
| duration | number | Interval in milliseconds for which to snooze the notifications. |
updateDatamethod
Signature
(id: string, data: unknown) => Promise<void>
Description
Sets or updates the arbitrary data associated with the notification which is available in the data property of the notification.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | ID of the notification whose data to update. |
|
| data | unknown | New notification data. |
ActionEventobject
Description
Describes a notification action event.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| action | string | The name of the notification action executed by the user. |
||
| type | "onaction" | Type of the notification event. |
ClickEventobject
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| type | "onclick" | Type of the notification event. |
ClickOptionsobject
Description
Options for the clicked notification.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| close | boolean | Flag indicating whether the clicked notification will be closed. |
Configurationobject
Description
Global notification settings.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| closeNotificationOnClick | boolean | If |
||
| enable | boolean | If |
||
| enableToasts | boolean | If |
||
| placement | NotificationPlacement | Describes the placement settings for the Notification Panel and the notification toasts. |
||
| sourceFilter | NotificationFilter | Filter with names of apps that are allowed or not allowed to raise notifications. |
||
| toastExpiry | number | Interval in seconds after which the notification toasts will be hidden. |
||
| toasts | { mode?: "single" | "stacked"; stackBy?: "application" | "severity"; } | Notification toast settings. |
ErrorEventobject
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| error | Error | Notification error. |
||
| type | "onerror" | Type of the notification event. |
InteropActionSettingsobject
Description
Settings for invoking an Interop method when a notification or a notification action is clicked.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| arguments | any | Arguments for the Interop method invocation. |
||
| method | string | Name of the Interop method to invoke. |
||
| target | "best" | "all" | Specifies which Interop servers to target when invoking the Interop method -
|
IOConnectNotificationOptionsobject
Description
Options for raising an io.Connect notification.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| actions | NotificationAction[] | Array of objects describing notification actions. The notification actions will be displayed as buttons in the notification. |
||
| badge | string | URL of an image to represent the notification as a badge. |
||
| body | string | Notification body text. |
||
| clickInterop | InteropActionSettings | Settings for invoking an Interop method when the notification is clicked. |
||
| data | any | Arbitrary data you have associated with the notification. |
||
| dir | "auto" | "ltr" | "rtl" | "auto" | The direction in which to display the notification. |
|
| icon | string | URL of an icon to be displayed in the notification. |
||
| id | string | Id for the notification. |
||
| image | string | URL of an image to be displayed in the notification. |
||
| lang | string | Language code of the notification. |
||
| panelExpiry | number | Interval in seconds after which the notification will be removed from the Notification Panel. |
||
| renotify | boolean | false | If |
|
| requireInteraction | boolean | false | If |
|
| severity | "Low" | "Medium" | "High" | "Critical" | "None" | Severity of the notification. |
||
| silent | boolean | false | If |
|
| source | string | Can be used for overwriting the name of the actual notification source. |
||
| state | State | "Active" | Notification state. |
|
| tag | string | ID tag of the notification. |
||
| timestamp | number | Specifies the time at which the notification is created or is applicable (past, present or future). |
||
| title | string | Title for the notification. |
||
| toastExpiry | number | Interval in seconds after which the notification toast will be hidden. |
||
| type | "Notification" | "Alert" | Type of the notification. |
||
| vibrate | number[] | Vibration pattern for the vibration hardware of the device to emit with the notification. If specified, |
Notificationobject
Description
Describes a raised notification.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| actions | NotificationAction[] | Array of objects describing the available notification actions. |
||
| appIcon | string | Icon of the app that has raised the notification. |
||
| appTitle | string | Title of the app that has raised the notification. |
||
| close | () => void | Closes the notification. |
||
| id | string | ID for the notification. |
||
| instanceId | string | ID of the app instance that has raised the notification. |
||
| onaction | (event: ActionEvent) => void | Notifies when a notification action has been clicked. |
||
| onclick | (event: ClickEvent) => void | Notifies when the notification has been clicked. |
||
| onclose | () => void | Notifies when the notification is closed. |
||
| onerror | (event: ErrorEvent) => void | Notifies when there is a notification error. |
||
| onshow | (event: ShowEvent) => void | Notifies when the notification has been shown. |
||
| state | State | State of the raised notification. |
NotificationActionobject
Description
Describes a notification action.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| action | string | Name of the notification action. |
||
| displayId | string | Unique ID for the notification action. This ID can be used in the |
||
| displayPath | string[] | List of |
||
| icon | string | Icon for the notification action. |
||
| interop | InteropActionSettings | Settings for invoking an Interop method when the notification action is clicked. |
||
| title | string | Title of the notification action that will be used in the notification action button. |
NotificationDataobject
Description
Describes a notification.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| actions | NotificationAction[] | Array of objects describing notification actions. The notification actions will be displayed as buttons in the notification. |
||
| appIcon | string | Icon of the app that has raised the notification. |
||
| appTitle | string | Title of the app that has raised the notification. |
||
| clickInterop | InteropActionSettings | Settings for invoking an Interop method when the notification is clicked. |
||
| id | string | ID for the notification. |
||
| instanceId | string | ID of the app instance that has raised the notification. |
||
| panelExpiry | number | Interval in seconds after which the notification will be removed from the Notification Panel. |
||
| severity | "Low" | "Medium" | "High" | "Critical" | "None" | Severity of the notification. |
||
| source | string | Can be used for overwriting the name of the actual notification source. |
||
| state | State | State of the raised notification. |
||
| title | string | Title for the notification. |
||
| toastExpiry | number | Interval in seconds after which the notification toast will be hidden. |
||
| type | "Notification" | "Alert" | Type of the notification. |
NotificationDefinitionobject
Description
Describes a web notification. For more details, see the web Notification interface.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| badge | string | URL of an image to represent the notification as a badge. |
||
| body | string | Notification body text. |
||
| data | any | Arbitrary data you have associated with the notification. |
||
| dir | "auto" | "ltr" | "rtl" | "auto" | The direction in which to display the notification. |
|
| icon | string | URL of an icon to be displayed in the notification. |
||
| image | string | URL of an image to be displayed in the notification. |
||
| lang | string | Language code of the notification. |
||
| renotify | boolean | false | If |
|
| requireInteraction | boolean | false | If |
|
| silent | boolean | false | If |
|
| tag | string | ID tag of the notification. |
||
| timestamp | number | Specifies the time at which the notification is created or is applicable (past, present or future). |
||
| vibrate | number[] | Vibration pattern for the vibration hardware of the device to emit with the notification. If specified, |
NotificationFilterobject
Description
Filter with names of apps that are allowed or not allowed to raise notifications.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| allowed | string[] | Array of names of apps allowed to raise notifications. |
||
| blocked | string[] | Array of names of apps not allowed to raise notifications. |
||
| muted | string[] | Array of names of apps that are currently muted. Available since version io.Connect Desktop 9.6 |
NotificationPanelAPIobject
Description
API for controlling the Notification Panel.
Methods
hidemethod
Signature
() => Promise<void>
Description
Hides the Notification Panel.
isVisiblemethod
Signature
() => Promise<boolean>
Description
Checks whether the Notification Panel is visible.
onVisibilityChangedmethod
Signature
(callback: (isVisible: boolean) => any) => UnsubscribeFunction
Description
Notifies when the visibility of the Notification Panel changes.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (isVisible: boolean) => any | Callback function for handling the event. |
showmethod
Signature
() => Promise<void>
Description
Shows the Notification Panel.
togglemethod
Signature
() => Promise<void>
Description
Toggles the visibility of the Notification Panel.
NotificationPlacementobject
Description
Settings for placing the Notification Panel and the notification toasts.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| panel | "left" | "right" | "right" | Defines the position of the Notification Panel on the screen. |
|
| toasts | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "bottom-right" | Defines the position of the notification toasts on the screen. |
ShowEventobject
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| type | "onshow" | Type of the notification event. |
Stateenumeration
Description
Notification states that are used by the platform when handling notifications. These states can also be used in your custom logic for processing notifications on the client or on the server side. Defaults to "Active".
"Active"- a notification can be marked as active when it is raised, but the user hasn't seen it, or interacted in any way with it yet;"Acknowledged"- a notification can be marked as acknowledged when the user has interacted with it by clicking on the notification or on an action in it;"Seen"- a notification can be marked as seen when the user has seen it (e.g., by opening the Notification Panel);"Closed"- a notification can be marked as closed when the user has closed the notification in the Notification Panel;"Stale"- a notification can be marked as stale after a predefined period of time;"Snoozed"- a notification can be marked as snoozed when the user snoozes it from the UI;"Processing"- a notification can be marked as"Processing"when its state is in the process of changing (e.g., the user interacts with a notification from the UI, you make a request to a remote service to update the notification state, and you are still waiting for a response);
- "Active"
- "Acknowledged"
- "Seen"
- "Closed"
- "Stale"
- "Snoozed"
- "Processing"