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>
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:
- Enable the API.
- Set an API password. This is separate from your login password.
- 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.