Run your workspace

Push notifications

Push notifications alert your team in the browser — and on installed PWAs — the moment something needs attention: a new lead, a visitor asking for a human, a new conversation, or a widget error. Unlike the in-tab "browser alerts" pill (which only toasts while a dashboard tab is open), push notifications arrive even when the tab is closed.

Web Push, not Firebase

Pitchbar uses the browser-native Web Push standard (VAPID) through your existing service worker. No third-party SDK, no vendor account, and no device tokens leaving your server — a clean fit for GDPR-sensitive installs.

What triggers a push

New lead captured — to every workspace owner/admin.
Human handoff requested — to operators who are available for live chat. Time-critical, so this is the highest-value push.
New conversation — the first message of a brand-new conversation (not every message), to owners/admins.
Widget / system error — to super_admins when the Widget Monitor records an error-severity event. Throttled to one alert per error type per 10 minutes so a failure storm raises a single notification.

Off the visitor hot path

Every push is sent from a queued job (the analytics queue), never from inside the live SSE stream. A push never slows a visitor's reply.

One-time setup (admin)

Web Push messages are signed with a VAPID keypair. Generate it once on the server:

php artisan pitchbar:webpush-vapid

The keypair is stored in the app_settings table (the private key encrypted at rest), so it survives deploys and needs no .env edit. Confirm it took under Settings → System → Mail, where the Web Push notifications panel shows Configured and the public key.

Flag	Effect
`--force`	Regenerate the keypair. This invalidates every existing browser subscription — operators must re-enable push — so only use it if a key was leaked.
`--subject=mailto:you@example.com`	Override the VAPID contact subject (defaults to a `mailto:` built from your mail "from" address).

Enabling push (each operator)

Once VAPID keys exist, every team member opts in from Settings → Profile → Push notifications by clicking Enable and accepting the browser permission prompt. The subscription is stored per-user, per-device — enabling on a laptop does not enable on a phone, and vice versa. Turn off removes the subscription for that device.

iOS needs an installed PWA

On iPhone/iPad, Web Push only works when the dashboard is added to the Home Screen (installed as a PWA) on iOS 16.4+. In a regular Safari tab the Enable button stays hidden because the browser reports no push support. Desktop Chrome/Edge/Firefox/Safari and Android Chrome work in a normal tab.

Send a test push

After enabling push in a browser, confirm the whole pipeline end-to-end with:

php artisan pitchbar:webpush-test --email=you@example.com

It sends a "Web Push is working" notification to that user's subscribed devices. Omit --email to target the first subscribed user, or pass --body="…" for custom text. The command fails loudly if no VAPID keys exist or the user has no subscription, so it doubles as a quick diagnostic.

Troubleshooting

Enable button is missing — the browser lacks push support (e.g. iOS Safari tab — install the PWA first), or no VAPID keys are configured (run the command above).
"Notifications are blocked" — the operator denied the browser permission. It can only be re-granted from the browser's site settings, then reload.
Enabled but nothing arrives — confirm a queue worker is running and draining the analytics queue (push jobs ride it). See Deployment.