Notifications
The Notifications system keeps you informed about important platform events that require attention. Inbox is the canonical in-app delivery surface; quiet hours and category preferences determine whether eligible notifications are also mirrored by email.
Before you begin
- Sign in to the organization whose preferences you want to change.
- To open Inbox, your role needs
notifications:read. - To open or save Settings → Notifications, your role needs
notifications:manage. - Email delivery also requires an account email, operator-configured SMTP, and the notification delivery worker. Changing quiet hours cannot make an unavailable email channel deliver.
- The settings page edits the signed-in user's preferences. It is not an organization-wide notification policy.
Notification sources
| Source | Examples |
|---|---|
| Escalation lifecycle | Escalation queued, assigned, claimed, resolved, or rejected |
| Disposable API-token lifecycle | Expiry, request or budget depletion, rotation, and revocation events |
| Billing and subscription state | Subscription changes that emit a billing notification |
| Conversation sharing | Access to a History conversation added or removed |
| Feedback | Confirmation that feedback was submitted |
| Managed broadcasts | Platform-managed notices when an operator sends a broadcast |
The current product does not automatically create Inbox notifications for export completion, gateway health or config reload, budget thresholds, or team invitations. Do not rely on those events appearing unless a future owning producer or managed broadcast explicitly creates them.
Viewing notifications
Open Inbox from the side navigation. The current top bar does not include a notification bell or preview popover.
Use the Inbox for:
- Chronological notification list
- Read/unread status
- Notification detail with action links
- Mark all as read
Notification detail
Each notification includes:
- Event type and timestamp
- Summary description
- An action link when the notification producer supplies one
Notification preferences
Open Settings → Notifications (/settings/notifications) to control quiet
hours and category-level email opt-outs. The API always preserves in_app as a
delivery channel, so these controls do not remove an already-created
notification from Inbox.
The current page does not render an email-channel switch. It preserves the email preference already stored for the current user, but you cannot enable or disable that channel from this screen.
Current opt-out categories include:
- Escalations
- System
- Security
- Billing
- Chat completions
- Sharing & collaboration
- Agent lifecycle
- Gateway lifecycle
These controls are stored even when no current notification producer emits a category; the source table above is the current producer inventory. For an implemented producer that maps to a listed category, an enabled category remains eligible for email when the email channel is enabled. Disabling it suppresses that category's email, not the notification's in-app copy.
Configure quiet hours
- Turn on Enable quiet hours.
- Choose a start time and end time in 24-hour
HH:MMformat. - Choose the timezone in which those times should be interpreted.
- Select Save preferences.
Quiet hours suppress email for non-critical categories while the current time
is inside the configured window. The start is included and the end is
excluded. When the start is later than the end, the window wraps across
midnight; for example, 22:00 to 08:00 covers late evening and the following
morning. Equal start and end times create a zero-length window rather than an
all-day quiet period.
The console currently offers UTC and these IANA timezone-backed choices:
US Eastern (America/New_York), US Central (America/Chicago), US Mountain
(America/Denver), US Pacific (America/Los_Angeles), Europe/London,
Europe/Berlin, and Asia/Tokyo. Region-based choices follow their timezone's
daylight-saving rules. This selection is independent of the display timezone
in profile settings.
Critical-category behavior
Notifications categorized as Escalations or Security bypass quiet hours. This is intentional: an overnight quiet-hours window must not delay email for those two critical buckets.
A category opt-out is a separate control and can still suppress that category's email. It cannot suppress the in-app copy, which is why the console notes that critical security alerts cannot be fully suppressed.
Save and verify preferences
After changing a time, timezone, or category:
- Select Save preferences and wait for the Notification preferences saved confirmation.
- Reload Settings → Notifications.
- Confirm that the quiet-hours switch, times, timezone, and category switches still match the intended values.
- For a practical check, use a non-critical notification created outside the window to verify normal email delivery. Do not generate a real security incident merely to test the critical bypass.
The console saves the full preference document and then reads it back. A success message proves that the update request succeeded; the reload check proves that the stored values can be read through the same user scope.
Deep links
Some notifications open the related console resource. Current examples include:
- Escalation notifications that open the relevant Inbox/escalation surface
- Conversation-share notifications that open
/history/{sessionId} - Disposable-token notifications that open
/tokens/{tokenId}
Notifications without an action link remain informational in Inbox.
Email delivery
When the stored preference includes email and an operator has configured SMTP and enabled the notification delivery worker, Keeptrusts can mirror eligible inbox notifications to the recipient's account email. The settings page itself does not expose the channel toggle.
Troubleshooting
| Symptom | What to check |
|---|---|
| Preferences fail to load | Do not save the displayed defaults over an unknown stored state. Reload the page first, then confirm the API is reachable and your role has notifications:manage. |
| Save returns a permission error | Ask an organization administrator to grant notifications:manage; Inbox-only notifications:read is not enough. |
| Save rejects a time or timezone | Use valid 24-hour HH:MM values and one of the timezone choices rendered by the console. The API rejects malformed times and unknown IANA timezone identifiers. |
| A notification arrives during quiet hours | Confirm its category. Escalations and Security intentionally bypass quiet hours; other categories should be suppressed only while the configured timezone is inside the saved window. |
| Inbox works but email does not | Confirm that email is present in the stored channel preference, the category is enabled, quiet hours are inactive, and the operator has configured the email delivery path. The current screen cannot toggle the email channel. |
| An expected event never appears in Inbox | Confirm that the event has an implemented notification producer. Export completion, gateway health or config reload, budget thresholds, and team invitations do not currently create Inbox notifications automatically. |