Skip to content

Web UI tour

The chatwire web UI is a React SPA served at http://localhost:8723. It loads automatically when the web agent starts and is the primary way to read and send messages.

Layout

┌─────────────────────────────────────────────┐
│  Sidebar  │         Chat view                │
│           │                                  │
│  Search   │  ┌─────────────────────────────┐ │
│           │  │  Header (contact name, info) │ │
│  Convo 1  │  ├─────────────────────────────┤ │
│  Convo 2  │  │                             │ │
│  Convo 3  │  │       Message list          │ │
│  ...      │  │                             │ │
│           │  ├─────────────────────────────┤ │
│  [Stats]  │  │       Compose box           │ │
│  ⚙ Settings│  └─────────────────────────────┘ │
└─────────────────────────────────────────────┘

The sidebar lists all conversations from chat.db, ordered by most recent message.

  • Unread badge — bold conversation name and count badge for unread conversations.
  • Group chat names — named groups show the group name; unnamed groups synthesize a name from participant first names.
  • Hiatus indicator — when hiatus mode is active, a yellow indicator appears at the bottom of the sidebar with an "End" button to cancel it.
  • Settings gear — bottom-left, opens the Settings page.
  • Plugin panels — plugins can register components in the sidebar.panel slot; the built-in Stats widget appears here when enabled.

Chat view header

The header shows the contact name (or group name), their handle, and quick-action buttons:

  • Pop out — opens the conversation in a separate browser window (useful for multi-monitor setups).
  • Hiatus — pin a hiatus toggle to this conversation's header.
  • Info — view group participants or contact details.

Message list

Messages display in reverse-chronological order (oldest at top, newest at bottom), iOS-style:

  • Blue bubbles — iMessages (your sent messages appear on the right)
  • Green bubbles — SMS/RCS messages
  • Sender names — shown above each bubble in group chats
  • Timestamps — shown on alternating messages to reduce visual noise
  • Tapback reactions — displayed as corner overlays on the bubble (❤️ 👍 👎 😂 ‼️ ❓ 🎉)
  • Read receipts — "Read at H:MM AM/PM" below the last message you sent
  • Quoted replies — iOS-style ghost bubbles showing the original message; click to scroll to it
  • Edited badge — a small "edited" indicator on messages that were changed (macOS 13+)
  • Location cards — map link cards for shared locations
  • Stickers / Memoji — displayed as image attachments

The message list is virtualized — only ~30 DOM nodes render at a time, regardless of conversation length. Scroll up to load older messages.

Compose box

  • Text input — multiline; Enter sends, Shift+Enter adds a new line (configurable in Settings).
  • Attachment button (clip icon) — pick a file or image to send.
  • Send button — click or press Enter.
  • Anti-spam fuse — when the fuse is active, a countdown banner appears above the compose box. At step 4+ (lockout), the compose area is replaced with a lockout notice.
  • Plugin extensions — plugins can register components in the compose.extension slot above the input.

PWA install

The web UI is a Progressive Web App. Install it for a standalone window with no browser chrome:

Chrome / Edge: - Click the install icon in the address bar (looks like a computer with a + sign) - Or: three-dot menu → "Install chatwire..."

iOS / Safari: - Tap the Share button → "Add to Home Screen" - Open from your Home Screen for a full-screen experience

Once installed, the app: - Loads cached conversations even when offline - Queues unsent messages when offline and retries on reconnect - Shows an "Update available" notification when a new version is deployed

Connection banner

When the server becomes unreachable, an amber Connection banner appears at the top of the chat view. It auto-dismisses with a "Reconnected" toast when the connection is restored.

The threshold for showing the banner is configurable: Settings → Notifications → Server offline alert.

Legacy UI

The original server-rendered UI is available at /?legacy=1 during the current release cycle. It will be removed in a future major version. Avoid building integrations or bookmarks that depend on it.

Settings

The Settings page is accessible via the gear icon in the sidebar. It's organized as an accordion with these sections:

  • Identity — your iMessage handles
  • Whitelist — contacts whose messages are relayed
  • Themes — color scheme and style picker
  • Notifications — ntfy topic, sound mode, connection alert
  • Automation — rules engine
  • Anti-spam — fuse configuration and unlock
  • Security — web UI password, API keys
  • Plugins — installed plugin settings
  • Export — download a backup of your config
  • Logs — structured log viewer
  • About — version info and service restart buttons

Plugin-registered settings sections appear after About.

Keyboard shortcuts

Shortcut Action
Enter Send message
Shift+Enter New line in compose
Esc Close popout window

More keyboard shortcuts are planned. Browser shortcuts (Cmd+R to reload, Cmd+L to focus URL bar) work normally.