Skip to content

Notifications

chatwire can push notifications to your phone or desktop when new messages arrive. There are three layers: ntfy push, browser web push, and the connection banner.

ntfy push notifications

ntfy is an open-source push notification service. chatwire sends a notification to your ntfy topic whenever a new inbound message arrives.

Setup

Install the plugin:

pipx inject chatwire chatwire-ntfy
launchctl kickstart -k gui/$(id -u)/dev.chatwire.bridge

Configure in Settings:

  1. Open Settings → Plugins → ntfy
  2. Enter your ntfy topic URL, e.g.: https://ntfy.sh/your-topic-name
  3. Click Save

Use a hard-to-guess topic name for basic security — ntfy.sh topics are public by default (anyone who knows the topic can subscribe or publish). You can also self-host ntfy for full privacy.

Subscribe on your phone:

  • Install the ntfy app (iOS / Android)
  • Subscribe to your topic
  • Notifications arrive within a few seconds of a new message

Notification depth

Control how much detail appears in the notification:

Depth What's shown
minimal "New message" — no sender or preview
sender Sender's name (or handle)
preview Sender's name + first ~100 characters of the message

Configure per-plugin in Settings → Notifications → Notification depth, or in ~/.chatwire/config.json:

{
  "notifications": {
    "notification_depth": {
      "default": "sender",
      "ntfy": "preview"
    }
  }
}

Browser web push (PWA)

When you install chatwire as a PWA (see Web UI tour), the browser can deliver push notifications even when the tab is closed.

The web push implementation uses VAPID — keys are generated automatically during chatwire setup. No external service required.

Enable browser push:

  1. Visit http://localhost:8723 in Chrome or Edge
  2. When prompted, allow notifications
  3. Notifications appear as standard system notifications

Web push only works when the device is on the same network as the Mac (or via Tailscale/VPN) — there's no cloud relay.

Connection banner

The ConnectionBanner appears in the web UI when the server has been unreachable for longer than the configured threshold.

  • Amber banner — server unreachable; the UI shows cached content
  • "Reconnected" toast — auto-dismisses when the connection returns

Configure the threshold:

Settings → Notifications → Server offline alert:

  • 30 seconds
  • 1 minute (default)
  • 2 minutes
  • 5 minutes
  • Disabled

Or in ~/.chatwire/config.json:

{
  "web": {
    "heartbeat_alert_seconds": 60
  }
}

Set to 0 to disable the banner entirely.

Sounds

The web UI can play a sound when a new message arrives.

Configure: Settings → Notifications → Sounds

Options: - Off — no sounds - Subtle — a quiet chime - Default — a standard notification sound

Sounds require the tab to be in focus or the PWA to be the active app.

macOS menu bar

The chatwire-toolbar script runs a macOS menu bar indicator:

  • Solid "ᴄ" icon — healthy; both bridge and web are running
  • Outline "ⓒ" icon — unhealthy; one or both services need attention

Click the icon for a dropdown showing: - Port and listening interface - Uptime and last message time - Per-service status - Restart buttons for bridge and web

The toolbar starts automatically with the bridge agent. If you see the outline icon, check chatwire doctor.