Notifications

Notifications help people notice work; they do not become the work. The Action and its event history remain authoritative even when a push is delayed, duplicated, or disabled.

What can appear in the notification center

The in-app record is user-scoped and tied to the active workspace. The notification list returns up to 100 published records, newest first.

Read and clear notifications

The dashboard Notifications page opens the linked Action and marks an unread record as read. You can also use the user-scoped API:

# List published notifications
curl 'https://api.actionbox.cloud/v1/notifications?unread_only=false' \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

# Read the navigation badge
curl https://api.actionbox.cloud/v1/notifications/summary \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

# Mark one read
curl -X POST https://api.actionbox.cloud/v1/notifications/ntf_…/read \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

# Mark every unread notification in the active workspace read
curl -X POST https://api.actionbox.cloud/v1/notifications/read-all \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

The summary returns unread_count; read-all also reports how many records were updated. Filtering or reading notifications never changes the linked Action.

Personal push preferences

In Settings → Notifications, each user can control optional push delivery:

The preferences API accepts the same controls:

curl -X PATCH https://api.actionbox.cloud/v1/notification-preferences \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "push_enabled": true,
    "new_action_enabled": true,
    "assignment_enabled": true,
    "reminder_enabled": true,
    "escalation_enabled": false,
    "priorities": ["high", "urgent"],
    "quiet_hours_enabled": true,
    "quiet_start_minute": 1320,
    "quiet_end_minute": 480,
    "timezone": "America/Toronto"
  }'

Quiet-hour values are minutes after midnight (1320 is 22:00 and 480 is 08:00 in the selected timezone). In-app notifications remain retained even when push is disabled.

Workspace reminders and escalations

Owners and admins control the workspace-wide policy at Settings → Notifications or through:

GET   /v1/workspaces/notification-policy
PATCH /v1/workspaces/notification-policy

The policy contains:

• reminders_enabled and reminder_minutes_before_expiry for assigned open Actions;
• escalations_enabled and escalation_minutes_after_creation for unanswered Actions; and
• escalation_priorities, which selects the priority levels that escalate.

Both minute values accept 1–10,080. Escalations target active owners and admins and exclude the current assignee. Updating the policy reschedules future notifications for open Actions.

Delivery behavior

• In-app notifications are durable records and are retained independently of push delivery.
• Push is optional and content-light: clients use the Action ID or change hint to refresh authoritative state.
• Operating-system policy, device connectivity, and provider networks can delay or suppress push delivery.
• Test Actions are isolated from live delivery and do not publish normal push hints or callback side effects in the hosted service.
• Resolving, cancelling, expiring, unassigning, or reassigning an Action cancels obsolete scheduled notification work.

Next: Assignments and routing, Devices and push inboxes, or Webhooks and callbacks.