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>
71 lines
3.6 KiB
Markdown
71 lines
3.6 KiB
Markdown
# 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.
|