Files
bubble/README.md
T
travandClaude Opus 5 a2b8f764db voip.ms Messages: Signal-style desktop SMS client
Electron + React app that imports the full voip.ms SMS history into a
local SQLite/FTS5 database, polls for new messages, sends SMS, resolves
names/photos from GNOME EDS address books, and supports global and
per-chat search with jump-to-message.

Data lives in ~/Documents/voipms-desktop-data (covered by Deja Dup) with
daily consistent snapshots.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-17 21:25:12 -07:00

3.6 KiB
Raw Blame History

voip.ms Messages

A Signal Desktop–style SMS client for voip.ms. It keeps your full message history on your own machine, lets you search it, and shows your GNOME contacts' names and photos.

Features

  • A conversation list on the left, with contact photos, previews, times, and unread badges. The chat opens on the right.
  • A full local copy of your history. On first run the app imports everything from voip.ms, working backwards in 90-day windows, and picks up where it left off if interrupted. After that it checks for new messages every 30 seconds (you can change this).
  • Search everything from the sidebar (Ctrl+F). Results show a highlighted preview, and clicking one jumps to that exact message. You can also search inside a single chat (Ctrl+Shift+F), using Enter and Shift+Enter to step through the matches.
  • New chat (Ctrl+N), with autocomplete from your contacts by name or number.
  • Contacts are read-only, straight from GNOME's Evolution Data Server caches: your Nextcloud CardDAV books and anything else GNOME Contacts shows. They reload automatically when the books sync.
  • Messages longer than 160 characters are split automatically. If a send fails, it's marked with Retry and Delete options.
  • Alt+↑/↓ moves between conversations.

Where your data lives

What Where Backed up?
Message database ~/Documents/voipms-desktop-data/messages.db ✅ Déjà Dup covers ~/Documents
Daily snapshots, last 7 kept ~/Documents/voipms-desktop-data/snapshots/ ✅
Settings ~/Documents/voipms-desktop-data/settings.json ✅
API password GNOME Keyring (via Electron safeStorage) → ~/.config/voipms-desktop/credentials.bin ❌ on purpose; you re-enter it after a restore
Contact photo cache ~/.config/voipms-desktop/photo-cache/ ❌ not needed

The snapshots are consistent SQLite copies, made daily and whenever you quit. So even if a backup catches the live database halfway through a write, the backup still holds a clean, restorable copy. To move the data folder, go to Settings → Storage → Move…. If you point it at a folder that already holds a messages.db, for example one restored from backup, the app uses that history.

Setup

In the voip.ms portal, go to Main Menu → SOAP & REST/JSON API and:

  1. Enable the API.
  2. Set an API password. This is separate from your login password.
  3. Add your IP address under Enable IP Addresses.

Then launch the app and enter your account email and API password.

Development

npm install
npm run dev              # run with hot reload
npm test                 # unit tests (run under Electron's Node for better-sqlite3)
npm run test:live        # also reads your real EDS address books (read-only)
npm run typecheck
npm run install-desktop  # build the AppImage and add a GNOME launcher

To work on the UI against fake data, without touching your real history, run:

VOIPMS_DEMO=1 VOIPMS_DATA_DIR=/tmp/voipms-demo npm run dev

Layout

src/main/       Electron main process
  voipms.ts       REST client (getDIDsInfo, getSMS, sendSMS)
  sync.ts         history backfill + polling
  db.ts           SQLite schema, FTS5 search, snapshots
  contacts.ts     EDS cache reader + vCard parser
  secrets.ts      keyring-encrypted credentials
  settings.ts     data folder + preferences
src/preload/    typed IPC bridge (window.api)
src/renderer/   React UI
src/shared/     types + phone-number helpers shared by both sides
resources/      icon, eds-sources.py (lists live EDS address books)

The message table already reserves kind and media_json columns for MMS support.