Skip to content

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

ts
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.

ts
const count = await window.Portal.notifications.archiveAll();

Returns

Resolves with a number.

catalog() ​

The vocabulary: every module's events, or only the one named.

ts
const notificationCatalog = await window.Portal.notifications.catalog(module);

Parameters

NameTypeRequiredDescription
modulestringNoThe 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.

ts
const notificationRecord = await window.Portal.notifications.create(payload);

Parameters

NameTypeRequiredDescription
payloadOmit<PortalNotificationRecord, 'id' | 'created_at' | 'updated_at' | 'is_read'>YesOne 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.

ts
await window.Portal.notifications.delete(id);

Parameters

NameTypeRequiredDescription
idstringYesThe record's id.

Returns

Resolves when the call has completed.

get() ​

Fetches one notification by id.

ts
const notificationRecord = await window.Portal.notifications.get(id);

Parameters

NameTypeRequiredDescription
idstringYesThe 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.

ts
const notificationRecords = await window.Portal.notifications.list(query);

Parameters

NameTypeRequiredDescription
queryPortalNotificationQueryOptionsNoFilters 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.

ts
const notificationMailHandlerSummarys = await window.Portal.notifications.mailHandlers();

Returns

Resolves with an array of PortalNotificationMailHandlerSummary.

markAllRead() ​

Marks every notification as read.

ts
await window.Portal.notifications.markAllRead();

Returns

Resolves when the call has completed.

markRead() ​

Marks one notification as read.

ts
const notificationRecord = await window.Portal.notifications.markRead(id);

Parameters

NameTypeRequiredDescription
idstringYesThe 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.

ts
await window.Portal.notifications.resend(id);

Parameters

NameTypeRequiredDescription
idnumberYesThe 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.

ts
const notificationRuleEntrys = await window.Portal.notifications.rules(module, scopeRef);

Parameters

NameTypeRequiredDescription
modulestringYesThe module key.
scopeRefstringNoThe 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.

ts
await window.Portal.notifications.saveRules(body);

Parameters

NameTypeRequiredDescription
bodyPortalNotificationSaveRulesBodyYesThe request body of Portal.notifications.saveRules().

Returns

Resolves when the call has completed.

sends() ​

The send ledger of one item, newest first.

ts
const notificationSendRows = await window.Portal.notifications.sends(module, scopeRef);

Parameters

NameTypeRequiredDescription
modulestringYesThe module key.
scopeRefstringYesThe 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).

ts
const count = await window.Portal.notifications.unreadCount();

Returns

Resolves with a number.

update() ​

Changes some fields of a notification.

ts
const notificationRecord = await window.Portal.notifications.update(id, payload);

Parameters

NameTypeRequiredDescription
idstringYesThe record's id.
payloadPortalNotificationUpdatePayloadYesThe 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.

NameTypeRequiredDescription
modulesPortalNotificationCatalogModule[]YesOne 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.

NameTypeRequiredDescription
keystringYesThe event's key, unique within its module. Use it as event in a rule.
labelstringYesHuman-readable name for settings screens.
appliesTostring[]YesThe kinds of item (scopes) this event can apply to.
scheduledbooleanYesTrue when the event fires on a schedule (for example "3 days before") rather than on an action.
alwaysOnbooleanYesTrue when the event cannot be switched off.
inboxDefaultbooleanYesWhether an inbox notification is sent by default when no rule is stored.
mailDefaultbooleanYesWhether an e-mail is sent by default when no rule is stored.
mailDelaySecondsnumberYesHow long the e-mail is delayed after the event, in seconds (0 = immediately).
variablesstring[]YesPlaceholders available in the title, body and e-mail text, for example 'customer_name'.
recipientModestringYesThe default recipient mode (see PortalNotificationRulePayload.recipient_mode).
hasDefaultEmailbooleanYesTrue when the platform ships a default e-mail text for the event.
attachedHandlersbooleanYesTrue when the owner attached mail handlers directly to this event.
mailUnavailablestring | nullYesWhy this event cannot send e-mail yet (null = it can).

PortalNotificationCatalogModule ​

One module's group of events inside PortalNotificationCatalog.

NameTypeRequiredDescription
modulestringYesThe module key, for example 'events'.
labelstringYesHuman-readable module name.
eventsPortalNotificationCatalogEvent[]YesEvery event the module can notify about.

PortalNotificationMailHandlerSummary ​

A mail handler an operator can choose to send notification e-mails from.

NameTypeRequiredDescription
reference_numstringYesThe handler's reference; use it as mail_handler_reference_num.
namestring | nullYesDisplay name.
fromstring | nullNoThe sender address, when known.
warningstring | nullNoA 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.

NameTypeRequiredDescription
pagenumberNo1-based page number.
limitnumberNoPage size.
unreadOnlybooleanNoOnly notifications that have not been read.
archivedOnlybooleanNoOnly archived notifications (the default list leaves them out).
categorystringNoOnly notifications of this category.
modulestringNoOnly notifications raised by this module.
severitystringNoOnly notifications of this severity. One of info, success, warning, danger.
ts
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).

NameTypeRequiredDescription
idstringYesUnique id of the notification; pass it to get, update, markRead and delete.
titlestringYesShort headline shown in the inbox.
bodystringNoLonger text shown under the title.
linkstringNoWhere clicking the notification should take the user (absolute or site-relative URL).
categorystringNoFree-form grouping label, useful for filtering (see PortalNotificationQueryOptions.category).
modulestringNoThe module that raised it, for example 'events' or 'ecommerce'.
eventstringNoThe event key within that module, for example 'registration.confirmed'.
severitystringNoVisual importance; the reference UI colours the notification by it. One of info, success, warning, danger.
subject_refstringNoReference of the thing the notification is about (an order, a booking...).
scope_refstringNoReference of the item (store, event, calendar...) the notification belongs to.
dedupe_keystringNoWhen set, a second notification with the same key replaces rather than duplicates the first.
is_readbooleanYesTrue once the user has read it.
is_archivedbooleanNoTrue once archived; archived notifications are hidden from the default list.
created_atstringYesISO timestamp of creation.
updated_atstringNoISO timestamp of the last change.
metadataRecord<string, unknown>NoFree-form extra data attached by whoever created the notification.
ts
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.

NameTypeRequiredDescription
eventstringYesThe event key.
rulePortalNotificationStoredRule | nullYesThe rule stored for this item, or null when it inherits.
effectiveobjectYesThe result after inheritance: what will actually happen.
effective.inbox_activebooleanYesAn inbox notification will be created.
effective.mail_activebooleanYesAn e-mail will be sent.
effective.sourcestringYesrule | module | default | none
effective.uses_attached_handlersbooleanYesTrue when handlers attached to the event are used instead of a single handler.

PortalNotificationRulePayload ​

One rule to save with Portal.notifications.saveRules().

NameTypeRequiredDescription
eventstringYesThe event key the rule is for.
is_activebooleanYesSend e-mail for this event.
inbox_activebooleanYesCreate an inbox notification for this event.
mail_handler_reference_numstringYesThe mail handler to send from (see Portal.notifications.mailHandlers()).
recipient_modestringYesWho 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_emailsstring[]NoThe addresses to use with recipient_mode: 'custom'.
days_beforenumber[]NoFor scheduled events: days before the date to send each reminder.
inbox_titlestringNoCustom inbox headline.
inbox_bodystringNoCustom inbox body.

PortalNotificationSaveRulesBody ​

The request body of Portal.notifications.saveRules().

NameTypeRequiredDescription
modulestringYesThe module key, for example 'events'.
scope_refstringYesThe item the rules are for (an event, a store...); '' = the module-wide rules.
rulesPortalNotificationRulePayload[]YesThe complete rule list for that item.

PortalNotificationSendRow ​

One line of the send ledger returned by Portal.notifications.sends().

NameTypeRequiredDescription
idnumberYesLedger id; pass it to resend().
eventstringYesThe event that caused the send.
recipientstringYesThe address the e-mail went (or was meant) to.
statusstringYessent, failed, skipped,...
errorstring | nullYesThe failure or skip reason, or null.
sent_atstring | nullYesWhen it was actually sent, or null if it was not.
created_atstring | nullYesWhen the send was queued.

PortalNotificationStoredRule ​

A notification rule as it is stored for one item and event (the owner's override of the defaults).

NameTypeRequiredDescription
reference_numstringYesThe rule's own reference.
eventstringYesThe event key this rule is for.
mail_activebooleanYesWhether e-mail is sent for the event.
inbox_activebooleanYesWhether an inbox notification is created for the event.
mail_handler_reference_numstring | nullYesThe mail handler (e-mail template and sender) used, or null for the default.
recipient_modestring | nullYesWho receives the e-mail; null = the event's default.
recipient_emailsstring[] | nullYesAddresses used with recipient mode 'custom'.
days_beforenumber[] | nullYesFor scheduled events: how many days before the date to send (one entry per reminder).
send_window_hournumber | nullYesFor scheduled events: the hour of day (0-23) reminders go out.
inbox_titlestring | nullYesCustom inbox headline, or null for the default text.
inbox_bodystring | nullYesCustom inbox body, or null for the default text.

PortalNotificationUpdatePayload ​

The fields Portal.notifications.update() may change. Send only what changes.

NameTypeRequiredDescription
is_readbooleanNoMark as read (true) or unread (false).
is_archivedbooleanNoArchive (true) or restore (false).
titlestringNoReplace the headline.
bodystringNoReplace the body text.
linkstringNoReplace the link.
metadataRecord<string, unknown>NoReplace the metadata object.
ts
const id = 'NOTIFICATION_ID';
await window.Portal.notifications.update(id, { is_archived: true });