Notifications
The signed-in user's inbox, plus the operator's notification rules. The calls use the dashboard session, so the user must be signed in to the dashboard.
Quick start
Show an unread badge and open the first notification
const unread = await window.Portal.notifications.unreadCount();
const first = await window.Portal.notifications.list({ unreadOnly: true, limit: 1 });
console.log(unread, 'unread');
if (first.length > 0) {
await window.Portal.notifications.markRead(first[0].id);
}API reference
window.Portal.notifications
Portal.notifications — the signed-in user's inbox plus the operator's notification rules. The calls use the dashboard session, so the user must be signed in to the dashboard.
archiveAll()
Archives every notification; nothing is deleted. Resolves with how many were archived.
const count = await window.Portal.notifications.archiveAll();Returns
Resolves with a number.
catalog()
The vocabulary: every module's events, or only the one named.
const notificationCatalog = await window.Portal.notifications.catalog(module);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
module | string | No | The module key. |
Returns
Resolves with a PortalNotificationCatalog: The notification vocabulary returned by Portal.notifications.catalog(): every module and its events.
create()
Creates a notification. The server fills id, created_at, updated_at and is_read.
const notificationRecord = await window.Portal.notifications.create(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | Omit<PortalNotificationRecord, 'id' | 'created_at' | 'updated_at' | 'is_read'> | Yes | One notification in a user's inbox (the bell / inbox UI reads these). |
Returns
Resolves with a PortalNotificationRecord: One notification in a user's inbox (the bell / inbox UI reads these).
delete()
Permanently deletes one notification.
await window.Portal.notifications.delete(id);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The record's id. |
Returns
Resolves when the call has completed.
get()
Fetches one notification by id.
const notificationRecord = await window.Portal.notifications.get(id);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The record's id. |
Returns
Resolves with a PortalNotificationRecord: One notification in a user's inbox (the bell / inbox UI reads these).
list()
Lists notifications, newest first, one page at a time. See PortalNotificationQueryOptions.
const notificationRecords = await window.Portal.notifications.list(query);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
query | PortalNotificationQueryOptions | No | Filters and paging for Portal.notifications.list(). |
Returns
Resolves with an array of PortalNotificationRecord.
mailHandlers()
The mail handlers an operator can send a notification e-mail from.
const notificationMailHandlerSummarys = await window.Portal.notifications.mailHandlers();Returns
Resolves with an array of PortalNotificationMailHandlerSummary.
markAllRead()
Marks every notification as read.
await window.Portal.notifications.markAllRead();Returns
Resolves when the call has completed.
markRead()
Marks one notification as read.
const notificationRecord = await window.Portal.notifications.markRead(id);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The record's id. |
Returns
Resolves with a PortalNotificationRecord: One notification in a user's inbox (the bell / inbox UI reads these).
resend()
Clears a failed or skipped send so it may go out again.
await window.Portal.notifications.resend(id);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | number | Yes | The record's id. |
Returns
Resolves when the call has completed.
rules()
The rules stored for one item (scopeRef '' = the module-wide ones), each with what applies now.
const notificationRuleEntrys = await window.Portal.notifications.rules(module, scopeRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
module | string | Yes | The module key. |
scopeRef | string | No | The item's reference; an empty string means the module-wide rules. |
Returns
Resolves with an array of PortalNotificationRuleEntry.
saveRules()
Saves the rules of one item. Rejects with the server's own message when it refuses.
await window.Portal.notifications.saveRules(body);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
body | PortalNotificationSaveRulesBody | Yes | The request body of Portal.notifications.saveRules(). |
Returns
Resolves when the call has completed.
sends()
The send ledger of one item, newest first.
const notificationSendRows = await window.Portal.notifications.sends(module, scopeRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
module | string | Yes | The module key. |
scopeRef | string | Yes | The item's reference; an empty string means the module-wide rules. |
Returns
Resolves with an array of PortalNotificationSendRow.
unreadCount()
The true number of unread, non-archived notifications (the list returns one page only).
const count = await window.Portal.notifications.unreadCount();Returns
Resolves with a number.
update()
Changes some fields of a notification.
const notificationRecord = await window.Portal.notifications.update(id, payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The record's id. |
payload | PortalNotificationUpdatePayload | Yes | The fields Portal.notifications.update() may change. |
Returns
Resolves with a PortalNotificationRecord: One notification in a user's inbox (the bell / inbox UI reads these).
Types
PortalNotificationCatalog
The notification vocabulary returned by Portal.notifications.catalog(): every module and its events.
| Name | Type | Required | Description |
|---|---|---|---|
modules | PortalNotificationCatalogModule[] | Yes | One entry per module (or only the requested one). |
PortalNotificationCatalogEvent
One event in the notification vocabulary: something a module can notify about, with its defaults and what it is able to send. Returned inside PortalNotificationCatalog.
| Name | Type | Required | Description |
|---|---|---|---|
key | string | Yes | The event's key, unique within its module. Use it as event in a rule. |
label | string | Yes | Human-readable name for settings screens. |
appliesTo | string[] | Yes | The kinds of item (scopes) this event can apply to. |
scheduled | boolean | Yes | True when the event fires on a schedule (for example "3 days before") rather than on an action. |
alwaysOn | boolean | Yes | True when the event cannot be switched off. |
inboxDefault | boolean | Yes | Whether an inbox notification is sent by default when no rule is stored. |
mailDefault | boolean | Yes | Whether an e-mail is sent by default when no rule is stored. |
mailDelaySeconds | number | Yes | How long the e-mail is delayed after the event, in seconds (0 = immediately). |
variables | string[] | Yes | Placeholders available in the title, body and e-mail text, for example 'customer_name'. |
recipientMode | string | Yes | The default recipient mode (see PortalNotificationRulePayload.recipient_mode). |
hasDefaultEmail | boolean | Yes | True when the platform ships a default e-mail text for the event. |
attachedHandlers | boolean | Yes | True when the owner attached mail handlers directly to this event. |
mailUnavailable | string | null | Yes | Why this event cannot send e-mail yet (null = it can). |
PortalNotificationCatalogModule
One module's group of events inside PortalNotificationCatalog.
| Name | Type | Required | Description |
|---|---|---|---|
module | string | Yes | The module key, for example 'events'. |
label | string | Yes | Human-readable module name. |
events | PortalNotificationCatalogEvent[] | Yes | Every event the module can notify about. |
PortalNotificationMailHandlerSummary
A mail handler an operator can choose to send notification e-mails from.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The handler's reference; use it as mail_handler_reference_num. |
name | string | null | Yes | Display name. |
from | string | null | No | The sender address, when known. |
warning | string | null | No | A problem with the handler (for example an unverified sender), when there is one. |
PortalNotificationQueryOptions
Filters and paging for Portal.notifications.list(). Every field is optional.
| Name | Type | Required | Description |
|---|---|---|---|
page | number | No | 1-based page number. |
limit | number | No | Page size. |
unreadOnly | boolean | No | Only notifications that have not been read. |
archivedOnly | boolean | No | Only archived notifications (the default list leaves them out). |
category | string | No | Only notifications of this category. |
module | string | No | Only notifications raised by this module. |
severity | string | No | Only notifications of this severity. One of info, success, warning, danger. |
const page = await window.Portal.notifications.list({ page: 2, limit: 20, module: 'events', severity: 'warning' });
console.log(page.length);PortalNotificationRecord
One notification in a user's inbox (the bell / inbox UI reads these).
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Unique id of the notification; pass it to get, update, markRead and delete. |
title | string | Yes | Short headline shown in the inbox. |
body | string | No | Longer text shown under the title. |
link | string | No | Where clicking the notification should take the user (absolute or site-relative URL). |
category | string | No | Free-form grouping label, useful for filtering (see PortalNotificationQueryOptions.category). |
module | string | No | The module that raised it, for example 'events' or 'ecommerce'. |
event | string | No | The event key within that module, for example 'registration.confirmed'. |
severity | string | No | Visual importance; the reference UI colours the notification by it. One of info, success, warning, danger. |
subject_ref | string | No | Reference of the thing the notification is about (an order, a booking...). |
scope_ref | string | No | Reference of the item (store, event, calendar...) the notification belongs to. |
dedupe_key | string | No | When set, a second notification with the same key replaces rather than duplicates the first. |
is_read | boolean | Yes | True once the user has read it. |
is_archived | boolean | No | True once archived; archived notifications are hidden from the default list. |
created_at | string | Yes | ISO timestamp of creation. |
updated_at | string | No | ISO timestamp of the last change. |
metadata | Record<string, unknown> | No | Free-form extra data attached by whoever created the notification. |
const items = await window.Portal.notifications.list({ unreadOnly: true });
items.forEach((n) => console.log(n.severity, n.title, n.link));PortalNotificationRuleEntry
One row of Portal.notifications.rules(): an event, its stored rule (if any) and what really applies now.
| Name | Type | Required | Description |
|---|---|---|---|
event | string | Yes | The event key. |
rule | PortalNotificationStoredRule | null | Yes | The rule stored for this item, or null when it inherits. |
effective | object | Yes | The result after inheritance: what will actually happen. |
effective.inbox_active | boolean | Yes | An inbox notification will be created. |
effective.mail_active | boolean | Yes | An e-mail will be sent. |
effective.source | string | Yes | rule | module | default | none |
effective.uses_attached_handlers | boolean | Yes | True when handlers attached to the event are used instead of a single handler. |
PortalNotificationRulePayload
One rule to save with Portal.notifications.saveRules().
| Name | Type | Required | Description |
|---|---|---|---|
event | string | Yes | The event key the rule is for. |
is_active | boolean | Yes | Send e-mail for this event. |
inbox_active | boolean | Yes | Create an inbox notification for this event. |
mail_handler_reference_num | string | Yes | The mail handler to send from (see Portal.notifications.mailHandlers()). |
recipient_mode | string | Yes | Who gets the e-mail: 'customer' (the person the event is about), 'handler' (the handler's own recipient), 'custom' (the addresses in recipient_emails) or 'operator' (the site's operators). One of customer, handler, custom, operator. |
recipient_emails | string[] | No | The addresses to use with recipient_mode: 'custom'. |
days_before | number[] | No | For scheduled events: days before the date to send each reminder. |
inbox_title | string | No | Custom inbox headline. |
inbox_body | string | No | Custom inbox body. |
PortalNotificationSaveRulesBody
The request body of Portal.notifications.saveRules().
| Name | Type | Required | Description |
|---|---|---|---|
module | string | Yes | The module key, for example 'events'. |
scope_ref | string | Yes | The item the rules are for (an event, a store...); '' = the module-wide rules. |
rules | PortalNotificationRulePayload[] | Yes | The complete rule list for that item. |
PortalNotificationSendRow
One line of the send ledger returned by Portal.notifications.sends().
| Name | Type | Required | Description |
|---|---|---|---|
id | number | Yes | Ledger id; pass it to resend(). |
event | string | Yes | The event that caused the send. |
recipient | string | Yes | The address the e-mail went (or was meant) to. |
status | string | Yes | sent, failed, skipped,... |
error | string | null | Yes | The failure or skip reason, or null. |
sent_at | string | null | Yes | When it was actually sent, or null if it was not. |
created_at | string | null | Yes | When the send was queued. |
PortalNotificationStoredRule
A notification rule as it is stored for one item and event (the owner's override of the defaults).
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The rule's own reference. |
event | string | Yes | The event key this rule is for. |
mail_active | boolean | Yes | Whether e-mail is sent for the event. |
inbox_active | boolean | Yes | Whether an inbox notification is created for the event. |
mail_handler_reference_num | string | null | Yes | The mail handler (e-mail template and sender) used, or null for the default. |
recipient_mode | string | null | Yes | Who receives the e-mail; null = the event's default. |
recipient_emails | string[] | null | Yes | Addresses used with recipient mode 'custom'. |
days_before | number[] | null | Yes | For scheduled events: how many days before the date to send (one entry per reminder). |
send_window_hour | number | null | Yes | For scheduled events: the hour of day (0-23) reminders go out. |
inbox_title | string | null | Yes | Custom inbox headline, or null for the default text. |
inbox_body | string | null | Yes | Custom inbox body, or null for the default text. |
PortalNotificationUpdatePayload
The fields Portal.notifications.update() may change. Send only what changes.
| Name | Type | Required | Description |
|---|---|---|---|
is_read | boolean | No | Mark as read (true) or unread (false). |
is_archived | boolean | No | Archive (true) or restore (false). |
title | string | No | Replace the headline. |
body | string | No | Replace the body text. |
link | string | No | Replace the link. |
metadata | Record<string, unknown> | No | Replace the metadata object. |
const id = 'NOTIFICATION_ID';
await window.Portal.notifications.update(id, { is_archived: true });