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>
This commit is contained in:
2026-09-17 21:25:12 -07:00
co-authored by Claude Opus 5
commit a2b8f764db
47 changed files with 10956 additions and 0 deletions
+70
View File
@@ -0,0 +1,70 @@
# voip.ms Messages
A Signal Desktop–style SMS client for [voip.ms](https://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
```bash
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:
```bash
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.