SMS, picture MMS, voicemail, and phone calls for VoIP.ms, built for people who run more than one number.
Working, and used daily on a real phone. Sending, threaded history, delivery status, notifications, configurable polling, and MMS photos all work. Photos are fetched with a size cap, identified from their bytes, cached, and shown whole with a tap to open them larger. Voicemail has its own tab: mailboxes, transcripts where your account has them, playback with seeking, and listened state written back to the account. New recordings notify like new texts do. The phone is also a phone: calls arrive and go out over the account's SIP registration, ring through Android's own call stack, and are answered from the lock screen. Sending media is not built.
Not affiliated with or endorsed by VoIP.ms. This is a third-party client that talks to their public API using credentials you supply.
Most VoIP.ms clients put every number into one conversation list and treat the destination number as a detail. This app starts from the number instead. The home screen lists your DIDs with their message and unread counts. Open one and you get its conversations, then a thread with the composer at the bottom.
Nothing is fetched for a number until you open it, so a first launch costs a single request. Opening fills the last 30 days and marks that history read. After that the poll fetches a window starting a day before the last one ended, which catches late arrivals without re-reading the month. A load-more control pulls 30 days per tap down to a two-year floor.
- Numbers first. One row per DID with message and unread counts. Numbers the
account cannot text are hidden, because the API reports
sms_enabledand there is no point listing a number that cannot receive anything. - Optimistic sending. The bubble appears before the request goes out, is confirmed by the id the API returns, and is removed with the draft restored if the send fails.
- Delivery status from the carrier, shown on sent messages and in red when undelivered or failed.
- Notifications. One per conversation with the newest text. The thread you are reading never notifies, and opening a thread clears its notification.
- A status strip on both lists, showing how long the last refresh took and how long until the next background run.
- Cadence you choose. 30 s, 60 s, 2 minutes, or off while a number is open, and 15, 30, or 60 minutes in the background.
- MMS photos. A picture arrives, is downloaded over a capped stream, identified from its first bytes rather than its URL, cached under a hash of the link, and drawn at its own aspect ratio so nothing is cropped. Tap it to open it larger, with a Close button and the back gesture both working. Attachments that are not pictures are handed to another app instead: audio plays inline when the server has the bytes, and video, OGG, MIDI, and PDF open externally.
- Credentials in Keystore-backed encrypted preferences. The database is local SQLite and is never synced anywhere.
- Voicemail, in its own tab. Every mailbox on the account is listed with its count of new messages, and each recording shows its transcript when the account has transcription enabled. Audio plays inline with 5 second seeking, is cached so a replay costs nothing, and playing it marks the message listened through the API. The window starts at 30 days, older recordings load on request, and messages reconcile by mailbox, folder, and message number rather than by position, so one that arrives late or is deleted elsewhere does not shift the rest.
- Voicemail notifications. Voicemail polls in the same pass as texts, on the same cadence. A mailbox whose new count rises gets one notification, replaced as the count grows, saying how many are waiting. It is on its own channel, so it can be silenced without silencing texts, and it never fires for the mailbox you are looking at. The count comes from the mailbox list, one request for the whole account, so a background poll never downloads a recording.
- Calls, in its own tab. A number can be chosen to answer here instead of at the provider, and the dialer places calls from a number you pick. Both directions go through Android's own call stack, so the lock screen, earpiece, speaker, Bluetooth and Do Not Disturb behave the way they do for a mobile call, and the incoming screen is the app's own, over the keyguard. A foreground service keeps the SIP registration alive with the app closed, and both a reboot and an app update put it back without opening anything. Calls are over the account's SIP registration, not the cellular radio.
Said plainly, because you will hit these:
- Attachments other than pictures are unreliable. A photo renders. Audio plays inline, and video, OGG, MIDI, and PDF open in another app, but only when the media link actually returns bytes. One real voice note arrived with an empty body behind its link, which shows as an empty attachment rather than playing; that is the server having nothing to serve, not a rendering fault. Sending media is not built.
- Numbers, not names. There is no contact lookup or avatar.
- No push. Latency is bounded by the poll interval, which is between 15 and 60 minutes in the background.
notes/BACKLOG.md in a working copy ranks these by value per hour, with the
implementation notes for each.
| Path | What |
|---|---|
android/ |
Android app, Kotlin and Compose. Gradle root, module in android/app/ |
tools/mock_voipms.py |
A stand-in REST endpoint, for testing without touching real messages |
relay/ |
Optional push relay, four implementations of one contract. Not wired to the app |
bench/ |
Cost and latency bench for those implementations |
deploy/ |
Cloud-init, Caddy, and quadlet for self-hosting the relay. Not written yet |
cd android
./gradlew :app:assembleDebug # android/app/build/outputs/apk/debug/app-debug.apk
./gradlew :app:testDebugUnitTest # unit tests, Robolectric included
adb install -r app/build/outputs/apk/debug/app-debug.apkRequires JDK 17. Compose BOM 2026.09.00 forces compileSdk 37. AGP 9 carries
Kotlin, so org.jetbrains.kotlin.android must not be applied.
The tests cover SMS segmentation, link matching, time formatting, the VoIP.ms
request and response shapes, and the store. notes/STATUS.md lists the gaps.
tools/mock_voipms.py answers getDIDsInfo, getMMS, getSMS, and sendSMS
with the shapes the real API uses, logs every call with a timestamp, and can be
told to fail, delay, or accept an injected inbound message. Point the app at it by
long-pressing the "Sync" heading in Settings and entering
http://10.0.2.2:8765/rest.php on an emulator. Clear the field to go back to
VoIP.ms. The app bar reads "not the real API" while an override is active.
Every push builds a signed APK and publishes it as a prerelease.
- Obtainium: add this repository as an app source and allow prereleases. It offers each new build, which is how the app gets onto a phone.
- By hand: download the APK from the latest release.
The version lives in android/version.properties, which is committed. Nothing
computes a version during a build, so a commit always produces the same numbers:
0.11.160449 / 11160449 at the time of writing, meaning months since December
2025, then day and time. scripts/version.sh write rewrites that file from the
clock and refuses to run under CI, so the file only ever changes when a person
commits it.
Bump it and commit before pushing. The release tag comes from the version, so a push without a bump reuses the existing tag, and that tag stays pinned to the commit that created it.
APKs are signed with a key kept in repository secrets. With no secrets the build
is debug-signed and its filename ends in -debugsigned. A debug-signed install
cannot be upgraded by a signed one later, so add the secrets before entering real
credentials. notes/DECISIONS.md D22 has the detail.
The app works with no relay and no distributor installed. It polls VoIP.ms once per number per tick, over a window with a fixed overlap so nothing is missed at the boundary. Push is optional and would only improve latency. Credentials live in Keystore-backed encrypted preferences. The database is local SQLite and is never synced anywhere.
Calling does not change that. The phone registers as a SIP handset with the provider so calls can arrive, which is a second connection to the same account, not a push service and not a relay; texts, calls, and voicemail are all read from the same API.
MIT. See LICENSE. Everything here is new code. The prior art we
studied is Apache-2.0 and it told us what to avoid, not what to copy, so no
upstream obligation attaches. F-Droid takes MIT as the SPDX identifier.
Prior art: voipms-sms-client
by Michael Kourlas, and voipms-mms-android-client
by VerbalP. Both map this API far enough to show where its sharp edges are. No
code was taken from either, and the design diverges where they struggle. The API
reference used during development is VoIP.ms's own documentation and is not
redistributed here.