Desktop: - Search lists chats whose own name matches first, so a named group isn't pushed out of the top 8 by chats that merely include a member. Android (Rabbit R1) app, 0.2.0: - Pull the chat list past its top for a search box (name, person, number, then group members; archived chats too; Back clears it). - Swipe right to left marks a chat unread / read over a magenta band; left to right still archives (SwipeActions replaces SwipeArchive). - Google Voice chats don't offer voice notes in the paperclip bubble. - Chats open with their newest 60 messages, then the full history; marking read (and the Google Voice network call) waits until they're on screen. Cached pictures show at once, and one slow download no longer blocks the other images. Fixed a contacts reload race. - Sandbox data gains filler chats, a named group and a 4,000-message chat. Also: the Android app, Google Voice support, media, export, emoji and the other work since the first commit, and a CLAUDE.md carrying the privacy rule.
5.9 KiB
bubble
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.
- MMS: photos, video and audio appear inline in the chat. Click a photo to view it full size or save it. You can attach up to 3 files with the paperclip, by drag-and-drop, or by pasting. Photos too big for voip.ms (the budget is 900 KB each) are shrunk automatically before sending.
- Emoji shortcodes: type
:and at least two letters, for example:jo, to get matching emoji. Pick one with ↑/↓ and Tab/Enter or by clicking it; Esc closes the list. A finished:joy:converts on its own. The shortcodes are Signal's and Slack's, from emoji-datasource;npm run gen:emojiregenerates them. - Alt+↑/↓ moves between conversations.
- Ctrl +/− zooms and Ctrl 0 resets. Choose Light, Dark, or System under Settings → Appearance.
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 |
✅ |
| MMS photos and attachments (cached on arrival) | ~/Documents/voipms-desktop-data/media/ |
✅ |
| 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.
Apple-style emoji (optional)
To look like Signal, the app uses an Apple Color Emoji font when one is installed, and falls back to Noto Color Emoji otherwise. To install it for your user only (about 116 MB):
curl -L -o ~/.local/share/fonts/AppleColorEmoji.ttf \
https://github.com/samuelngs/apple-emoji-linux/releases/latest/download/AppleColorEmoji-Linux.ttf
fc-cache -f
Alternatively, install the fonts-apple-color-emoji.rpm from the same release to make it available system-wide. Restart the app afterward.
Development
Dependencies are installed through Socket Firewall
(sfw), which checks every package, transitive ones included, against socket.dev
before npm downloads it. Install it once with npm i -g sfw, then use the
deps:* scripts instead of bare npm install (a Claude Code hook in
.claude/ enforces this for Claude):
npm run deps:install # after cloning or pulling changes to package-lock.json
npm run deps:add -- pkg # add a package
npm run deps:update # update within package.json's ranges
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 try the app or work on the UI without going near your real account, run it in a sandbox. Everything it uses (Electron profile, so no saved voip.ms password or Google sign-in, plus settings and the message database) lives under the given folder; it skips your address book and fills itself with made-up conversations, 1:1 and group, on a demo voip.ms number and a demo Google Voice number:
VOIPMS_SANDBOX=/tmp/voipms-sandbox npm run dev # or VOIPMS_DEMO=1, same folder
rm -rf /tmp/voipms-sandbox # start over
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.