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

71 lines
3.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.