# Notifications (Bell, Push, Email)

_Settings & Administration_

Per-user notification preferences. Three channels, three very different purposes:

🔔 Bell — the header icon inside CRMown. Lands instantly while you have CRMown open. A red badge counts unread items; click the bell to read the list.

📲 Push — system-level alert that pops on your screen even when CRMown is closed. On desktop it's the small toast in the corner of your OS (macOS Notification Center, Windows Action Center); on mobile it's the normal phone banner + lock-screen notification. Requires a one-time permission grant from your browser/device.

📬 Email — a daily digest summarizing what you missed, delivered to your login email.

Each CRMown user has their own settings; they don't inherit from the org. Defaults are "everything on for bell + push, email off" so every new user gets the normal experience out of the box, but each user can dial it back to just what matters to them.

## Steps
1. Go to Settings > Account and expand the 🔔 Notifications section.
2. Use "Pause all notifications" at the top as a quick off-switch — every channel silenced without losing your per-category settings.
3. Below that, the category × channel grid lets you turn each alert type on/off per channel: Bell (in-app header dropdown, fires only when CRMown is open), Push (OS-level alert that fires even when CRMown is closed), Email (daily digest).
4. Changes save instantly — no save button. A small "Saved" indicator confirms each toggle.

## Tips
- Categories: 💬 New messages · 💰 Deal & pipeline updates · 📋 Task due · 📅 Calendar reminders · 🤖 AI action approvals · 🛟 SOS tickets · ⏱ SLA warnings / breaches / escalations · ⚙️ System alerts · 📊 Batch job complete.
- When to use Push vs Bell: leave Bell on for everything (it's free, in-app only, never follows you around). Use Push for the handful of categories that actually warrant interrupting you when you're NOT in CRMown — typically new messages, AI approvals if you're OWNER/ADMIN, SLA warnings, and calendar reminders. Leave Push off for things you'll catch when you next open the tab (deal updates, batch completion, system alerts).
- How Push reaches you: the FIRST time you land in CRMown after enabling it, your browser asks "CRMown wants to send notifications — Allow / Block". Once allowed, the browser keeps a push subscription (even after you close the tab) and delivers alerts via the OS even if CRMown isn't running. Chrome / Edge / Safari / Firefox all support this. On mobile, the CRMown mobile app registers its own device token on login — no browser involved.
- What Push looks like: a small rectangular toast in your OS notification area with the alert title, a one-line preview, and the CRMown icon. Clicking it opens the relevant CRMown page directly (e.g. the pending AI action or the message thread).
- Role-gated categories (AI action approvals, SOS tickets) only fire for users who can act on them. Turning them off silences your own bell; the notifications still fan out to other approvers.
- The old master "Receive notifications" org-wide switch still wins — if an admin disabled it for your account, the per-category toggles have no effect. Ask them to re-enable.
- Bell badge in the header polls every 30s and also listens for real-time socket pushes, so your preferences take effect immediately without a page refresh.
- Email digest is currently a toggle-only — the daily-digest job isn't wired up yet. Enabling it saves the preference for when that lands.

## Example
A sales rep mutes everything except New messages + AI action approvals. Her bell now only pings when a prospect replies or the AI drafted a follow-up waiting on her sign-off. Her manager (ADMIN) keeps everything on + adds Pipeline updates + Task due to get cross-team visibility. Same org, two very different notification volumes — each person owns their own.

## Troubleshooting
- **I don't see the notifications panel** — It lives under Settings > Account > 🔔 Notifications (collapsible). If your Account tab is empty or broken, check the console for API errors — most likely /notifications/prefs returned 401. Fix: Scroll to the Account tab (first tab) and expand the Notifications section below Organization Members. If still empty, log out and back in to refresh your session token.
- **I toggled a category off but the bell still badges me for it** — The notification was queued BEFORE you changed the preference. Preference changes apply to future notifications only — not ones already in your inbox. Fix: Click "Mark all read" on the bell dropdown to clear the existing badge; new notifications will honor your updated preferences.
- **"Paused" badge shows but I'm still getting notifications** — Someone with admin access changed the master receiveNotifications flag, and your per-user pause is being overridden by a downstream system notification, OR you're seeing socket events (not notifications) from an open tab. Fix: Verify Settings > Account > Your Account > receive notifications is on, then re-toggle Pause. If problems persist, file a bug report — the paused state should silence every category.
- **Push notifications aren't arriving even though the toggle is on** — The browser or device hasn't registered a push subscription with CRMown. Most common: the permission prompt was dismissed or blocked the first time, so the browser never subscribed. Push delivery requires (1) the toggle ON in CRMown, (2) the browser/OS permission granted at the system level, AND (3) a subscription token registered on the server — all three. Fix: Browser (Chrome/Edge): open chrome://settings/content/notifications, find "app.crmown.io" or "staging.crmown.io" in the list, set to Allow. Then refresh CRMown — the app re-requests the subscription and you should see a confirmation toast. Safari: Safari menu > Settings > Websites > Notifications > find CRMown, set to Allow. Firefox: Preferences > Privacy & Security > Permissions > Notifications > manage Exceptions. Mobile: the CRMown mobile app asks for push permission on first login — if denied, go to your phone Settings > Apps > CRMown > Notifications and enable them, then log out and back in. If nothing works, try an incognito window — if push works there, a browser extension is interfering.
- **Push arrived but clicking it does nothing** — The browser killed the link handler (usually because your CRMown tab had been closed for too long and the notification payload points at a route that needs auth). Fix: Clicking a push notification opens CRMown at the relevant page; if you're signed out, it bounces you through login first. Log in and the intended page loads. If the click opens nothing at all, that's a browser bug — most reliable workaround is to open CRMown manually and check the bell dropdown.

## Plans
All plans include per-user notification preferences.