SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

Notifications & Comms

Notification channels, communication templates, customer emails, preferences, and the communication log.

Overview

Signals tells people about work in three places: the notification bell in the header, the email and real-time channels each person chooses under My Notifications, and customer emails such as invoices and statements. Administrators set company defaults for each notification type, edit the templates and layouts, review drafts before they go to customers, and browse the communication log.

Delivery starts with system defaults, then applies company settings and each person's preferences. Administrators may explicitly opt into installed plugin channels; personal preferences only narrow the company selection. Installing a plugin never enables delivery automatically. How channels, resolution and the delivery APIs work internally is described in Notification delivery internals.

Header notification bell

The header hosts <livewire:notifications.bell /> for every authenticated user with a linked account.

Element Behaviour
Bell icon Unread count badge (caps at 99+)
Slide-out pane Title "Notifications", paginated list, relative timestamps
Mark all read / per-item Read Clears database notifications
Footer link Notification preferences → /settings/notifications

Real-time updates arrive via Reverb on the user's private channel; the bell also polls every 60 seconds.

My Notifications (user settings)

Route: /settings/notifications (Settings sidebar → Notifications)

Per notification type (grouped by category):

  • Mute checkbox
  • Channel toggles — only channels your company has enabled (In-app, Email, SMS, Slack, Teams)

Click Save to persist preferences. Users cannot enable channels the tenant has disabled.

Admin notification settings

Route: /admin/settings/notifications (Admin → Preferences → Notifications) Permission: notifications.manage on mount and all actions

Header action Communication Log links to /admin/settings/communication-log. The same destination appears as a card on the admin landing page.

Delivery resolves from the type's defaults through company settings and each person's own settings. Company settings may opt into installed plugin channels; each person's settings can only narrow that selection.

Tabs

Tab Contents
Company defaults Categories, the notification list or matrix, and the notification editor
Preview a person Read-only grid of what one person gets after company and personal settings
Delivery channels Delivery drivers (configure / send test) and how to add a channel with a plugin
Recent communication log Latest outbound rows with a link to the full log
Retention Log retention, prune safety window, unsubscribe link lifetime

Delivery channels

One row per registered driver (In-App, Real-Time, Email) showing a status (Tested / Failing / Untested). Below the list, Add a channel with a plugin shows the three steps (create a plugin, implement a channel provider registered in the manifest, install and turn it on) with a link to the channel provider guide (hidden on cloud installs).

Outbound mail has a single home: Admin → Preferences → Email. The email card does not duplicate that form.

Action Purpose
Configure Slide-over with provider fields for non-email drivers (credentials masked on save)
Configure in Email settings Link on the email card to /admin/settings/email (admin.settings.email)
Send test Fires test delivery against the shared settings; email uses the current Email settings (falls back to the signed-in user's address when no recipient is entered)

Company defaults

List view. A rail of categories shows how many notifications in each send in-app alerts and email. Search finds notifications by name, description or key across categories. Each row shows the channels it sends on (on, off, or not used) and chips for Off, Always on, Everyone gets it (locked) and the audience.

Editor. Opening a notification shows one card per question, with a sticky In plain words summary ("When a rental is confirmed, the record's owner gets an in-app alert and an email…") and a save bar. Changes are a draft until Save Changes; leaving with unsaved changes asks first.

Card Purpose
How it is sent One switch per channel (In-app covers in-app and real-time together). Notifications that go to your team and customers have a switch set for each. Choose from the type’s core defaults and installed plugin channels. Dedicated authentication, digest and customer-communication mail retain their dedicated delivery paths.
Who gets it Recipient rules in plain words, with Edit Recipients (record owner, person who did it, role, roles chosen in settings, named person, assigned people, customer contact)
Can people turn it off? Let people turn this off — off locks the notification: personal settings no longer mute or narrow it. Sign-in emails are always sent; customer-only notifications have nothing to lock.
The email The email template(s) per warehouse with Edit Template, and a preview of the email with sample details in the default email layout

Bulk changes. Tick notifications (or a whole group, or everything shown; Shift-click ticks a range), then Change Selected: turn on or off, turn a channel on or off, stop or let people turn them off, add or replace recipient roles, or reset to defaults. The dialog says how many will change and how many are skipped because the setting doesn't apply.

Matrix view. Notifications as rows and On, each channel and each role as columns. Click a cell, a column heading (sets the whole column) or a row heading (sets every channel in the row); arrow keys move between cells. Unsaved changes are counted in a floating save bar and saved together.

Every save — editor, bulk or matrix — goes through one audited action and records notification_setting.updated per changed notification.

Communication template editor

Route: /admin/settings/communication-templates/{template}/edit Same unified editor as Templates. Type and warehouse chrome stay visible on communication rows.

Panel Contents
Title + Body HTML body with merge-field browser (search + insert)
Email layout Picker for email_layout_id on email-channel rows
SMS stats Segment counter when SMS channel applies
Version history Snapshots with change notes; Restore
Live preview Sample vs real entity; optional rental picker; rendered title/body/HTML
Send test Email-channel rows

System communication templates are read-only — Duplicate to customise creates an editable copy. System email templates stay editable and use Reset to Default instead.

Communication drafts

A draft is a customer communication that has been composed but not sent. It is a separate record from the communication log — the log says what went out, and a draft that is discarded was never a communication at all.

Drafts appear on the Communications tab of a rental, invoice, or account, above the log, showing who composed each one (including whether it was an AI agent).

Lifecycle — approving and sending are separate steps. The UI may chain them, but the model never collapses them.

Status Meaning Next
draft Composed, awaiting review. The only editable state. approve / discard
approved A person signed the content off. Frozen. send
discarded Rejected. Terminal — it can never be sent. —
sent Handed to the delivery pipeline; communication_log_id is populated. —

Free-text drafts. template_id and merge_data are optional. A draft composed as prose has no template at all; the approved artefact is always the rendered snapshot in subject_line / rendered_body.

What is delivered. Sending delivers the approved snapshot verbatim rather than re-rendering the template — a re-render at send time could produce something no human ever read. Everything else (opt-out checks, retries, delivery tracking, logging) is the same pipeline every other customer email uses. template_id is still recorded on the log for provenance.

A privacy-restricted recipient cannot receive a newly sent approved draft. The send action returns a validation error on notifiable_id before creating a communication log, changing the draft, or queuing delivery. The draft stays approved. Jobs queued before restriction still check the current restriction at delivery and suppress the message. Restriction retains communication preferences under the privacy policy; erasure removes them. Unrelated recipients retain their preferences and deliveries.

Permissions. communications.draft composes; communications.approve approves, discards, and sends. Approving, discarding and sending are all human-only by construction: holding the permission is not enough, the acting context must resolve to a person (or that person's API token). An AI agent may draft, never dispose of a draft — the MCP surface exposes create-communication-draft and deliberately nothing else. Sending shares communications.approve rather than taking a permission of its own, on purpose: whoever may sign off the content is trusted to release it.

Every step also requires view on the record the draft is about, so a caller only ever sees or acts on drafts for records they could read anyway; the draft index is scoped to the record types the caller may view.

The draft endpoints are listed in Notification delivery internals.

Communication templates

Index: /admin/settings/email-templates (Admin → Preferences → Templates) Edit: /admin/settings/communication-templates/{template}/edit

Per-warehouse communication templates are the single source of truth for transactional and auth email copy (magic-link sign-in, password reset, invitation, new-sign-in notice, daily digest) as well as billing and customer communications. TransactionalEmailResolver resolves warehouse template → hardcoded fallback; there is no parallel email_templates row for those type-keyed sends.

Type-less keys (test_email, embedding_budget_exceeded) and custom.* templates live on the same Templates index as a separate EmailTemplate model. The two tables are not merged.

Templates support version snapshots and restore, parallel to document templates. Communication versions use version; email versions use version_number. Compiled-segment cache is keyed off the communication version.

API: Communication Templates — CRUD plus version restore. The admin UI offers create, delete, duplicate, and send-test on the unified index.

Email layouts

Every outbound email is wrapped in a branded layout — the document shell, styles, header, body slot, and footer. The order in which a layout is chosen at send time is described in Notification delivery internals.

Layouts are database records edited at Admin → Preferences → Email Layouts, with a slot dialect ({{{ body }}} and friends), conditional blocks, escaped branding merge fields, version snapshots, and a live preview. Styles are inlined onto each element after rendering. The default layout is cached for an hour and busted by every layout write.

See Email Layouts.

Customer communications

Billing actions dispatch customer emails through DispatchBillingCustomerCommunication:

  • Invoice issued / emailed
  • Payment receipt
  • Account statement

Each send is logged in communication_log. Customers can opt out via signed unsubscribe links.

SettingTypeDefault
notifications.communication_log_retention_daysinteger365
notifications.communication_log_prune_safety_daysinteger7
notifications.unsubscribe_url_ttl_daysinteger365
notifications.inbound_signature_headerstringX-Signature
notifications.inbound_timestamp_headerstringX-Timestamp
notifications.inbound_tolerance_secondsinteger300

Communication log (admin)

Route: /admin/settings/communication-log Permission: notifications.manage + warehouse scoping on rental subjects Navigation: Admin landing → Preferences → Log; Notifications page header Open communication log

Filters: Status, Channel, Type, Recipient, From, To — Clear filters

Table: When, Type, Recipient, Channel, Status, Subject, and a row action to view the entry

Detail modal: rendered body, status timeline (Queued / Sent / Delivered / Opened), Pin / Unpin, failure reason callout

The same log table partial appears on invoice Communications, rental Communications, and account Communications tabs — scoped to that record.

Rental and account Communications tabs

Tab Route Gate
Rental /rentals/{rental}/communications rentals.view
Account /accounts/{account}/communications Account view policy

Both render paginated communication log entries for that record. The rental tab also carries the Conversations panel above the drafts and the log — one destination for everything said about the rental (see Conversations & Mentions).

Public unsubscribe

Signed URLs at GET /communications/unsubscribe/{account}?type={notification_type_key}.

The page shows masked email, explains the opt-out, and offers an Unsubscribe button (POST with CSRF). Success state confirms removal. Link lifetime follows Unsubscribe link lifetime (days) on the notifications admin page.

Permissions summary

Permission UI effect
notifications.manage Admin notifications, communication log, template editor
Authenticated user Bell, pane, /settings/notifications
accounts.view Account communications tab (via account access)

At a glance

Configure system-wide notification channels for each registered notification type. Requires notifications.manage.

The page is one sidebar item with five tabs: Company defaults, Preview a person, Delivery channels, Recent communication log, and Retention. Notifications are grouped by category, with a list view and editor, bulk changes, and a matrix view.

The communication log is that Recent communication log tab — not a nested Preferences sidebar item. The full-page log at /admin/settings/communication-log remains available from the tab and the Notifications header action.

Each notification type defines which channels are available and which are enabled by default. System-level overrides apply to all users unless individual users set their own preferences via profile settings or the Notification Preferences API.

Setting Key Description
Unsubscribe URL TTL notifications.unsubscribe_url_ttl_days Days until signed unsubscribe links expire (default 90)