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:emoji regenerates them.
  • Alt+↑/↓ moves between conversations.
  • Ctrl +/− zooms and Ctrl 0 resets. Choose Light, Dark, or System under Settings → Appearance, and the dark or inverted (lighter) icon.
  • The Rabbit's SIM, from here (Settings → Rabbit relay): with bubble as the Rabbit R1's texting app, its SIM is a third number to text from ("Rabbit SIM"), its texts show up here, and chat names and read/unread/archived stay in step with the Rabbit, no cable needed. It goes through a small relay on jai (server/bubble_relay.py, deployed with scripts/deploy-jai.sh), which only ever holds AES-256-GCM-sealed messages: the key lives on this computer and the Rabbit, never on jai. A text sent from here goes out at the Rabbit's next background check, so it can take a while; older photos come over when you open them.

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
Rabbit relay address, token and key GNOME Keyring → ~/.config/voip.ms Messages/relay.bin ❌ on purpose; reconnect and Sync to Rabbit after a restore

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.

The Rabbit relay (optional)

  1. scripts/deploy-jai.sh puts the relay on jai (its own folder, port 8080 on the tailscale address only); scripts/deploy-jai.sh --token prints its token.
  2. Settings → Rabbit relay: paste the token, Connect.
  3. Plug in the Rabbit and press Sync to Rabbit once: that hands it the address, token and the sealing key.

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.

S
Description
No description provided
Readme
3.4 MiB
Languages
TypeScript 49.1%
Java 38.3%
CSS 8.7%
Python 3.2%
Shell 0.5%
Other 0.1%