Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.
Calls service (protocol v0)
Status: draft. Builds on protocol v0; breaking changes are allowed until v1. License: CC BY 4.0.
A phone tells its PCs about its calls: who's calling, when it's answered, and when it ends. A PC can answer, decline or silence a ringing call, hang up, mute, switch to the speaker, hold, press keypad keys and change the volume of the call in progress, browse recent calls, and ask the phone to call a number. The call's audio stays on the phone; this service carries no sound.
1. Capabilities
| ID | Offered by | Meaning |
|---|---|---|
call.state |
phone | Reports its calls (needs the phone permission) |
call.control |
phone | Answers, declines, silences and hangs up calls, and changes their volume, when a PC asks |
call.incall |
phone | Also mutes, switches to the speaker, holds and presses keys on the call in progress, and reports those controls |
call.log |
phone | Lists recent calls (needs the call log permission) |
call.dial |
phone | Places a call (or opens the dialer with the number filled in) when a PC asks |
call.sims |
phone | Lists the SIMs it calls with, and places a call on the one a PC picks |
call.show |
PC | Shows calls, recent calls and the dialer, and wants call.log.changed |
A phone reports calls and answers call requests only for PCs that offer
call.show, and only while both devices allow it (the calls device
toggle, on by default, on each side).
2. Messages
On the control stream.
t = "call.state" b = {
id: text, // The phone's ID for this call: 1 to 64 bytes, the same in each of its messages
state: "ringing" | "active" | "ended",
? incoming: bool, // Default true; false for calls the phone's user made
? number: text, // At most 256 bytes, when the phone knows it
? name: text, // The contact's name, when the number is a contact
? photo: bytes, // The contact's photo, a JPEG of at most 64 KiB, with "ringing"
? missed: bool, // With "ended": it rang and nobody answered (default false)
? since: int, // With "active": when it was answered, in Unix milliseconds
? controls: { // With "active", from a phone offering call.incall
? muted: bool, // The phone's microphone is muted
? speaker: bool, // The sound is on the speaker
? held: bool, // The call is on hold
? can_hold: bool, // The call can be held
},
}
t = "call.action" id = n b = {
id: text,
action: "answer" | "decline" | "silence"
| "mute" | "unmute" | "speaker" | "earpiece" | "hold" | "unhold"
| "dtmf" | "volume_up" | "volume_down",
? digit: text, // With "dtmf": one of 0 to 9, * and #
}
t = "ok" re = n
t = "call.log" id = n b = { ? before: int, limit: uint } // 1 to 100
t = "call.log" re = n b = { entries: [ call_entry ] } // newest first
t = "call.log.changed" b = {} // phone → PC
t = "call.dial" id = n b = { number: text, ? sim: text } // sim: an id from call.sims
t = "ok" re = n
t = "call.sims" id = n b = {}
t = "call.sims" re = n b = { sims: [ { id: text, label: text } ], ? default: text }
call_entry = {
id: text,
number: text, // Who called, or who was called ("" when withheld)
? name: text, // The contact's name, when the number is a contact
direction: "incoming" | "outgoing" | "missed" | "rejected",
date: int, // When the call started, in Unix milliseconds
duration: uint, // Seconds on the call (0 when missed or not answered)
? photo: bytes, // The contact's photo, a JPEG of at most 16 KiB
}
2.1 call.state
Sent when a call starts ringing (and again when the phone learns more,
such as the number), when it's answered, whenever its controls change,
and when it ends. Not answered. A PC that connects during a call gets its
latest call.state right away.
controls is there only while the phone can change them: a PC shows
mute, speaker, hold and the keypad only then.
A call that was declined, on the phone or from a PC, ends without
missed.
2.2 call.action
answer: answers the ringing call; the conversation happens on the phone.decline: declines the ringing call, or hangs up the active one.silence: stops the phone ringing; the call still rings for the caller.volume_up,volume_down: the active call's volume (call.control).mute,unmute,speaker,earpiece,hold,unhold: as named, on the active call (call.incall). The new state comes back incall.state.dtmf: plays the keypad tonedigiton the active call (call.incall).
Errors: NOT_FOUND when id isn't the call in progress, or the action
doesn't fit its state (answer and silence need it ringing; the others,
except decline, need it active); DENIED when calls are off for the PC;
UNSUPPORTED for an unknown action, a dtmf without a valid digit, or
when the phone doesn't offer the capability the action needs.
2.3 call.log and call.log.changed
call.log pages back through the phone's recent calls, newest first:
before is the oldest date already shown. A phone answers with fewer
items than limit when the answer wouldn't fit in a frame (v0 §3),
dropping the oldest.
The phone sends call.log.changed to connected PCs that offer call.show
when its call log changes (debounced). PCs then ask again for what they
show.
Errors: DENIED when calls are off for the PC, UNSUPPORTED when the
phone doesn't offer call.log.
2.4 call.dial
call.dial asks the phone to call number (1 to 256 bytes, not blank). With
CALL_PHONE permission the phone places the call directly
(Intent.ACTION_CALL); if that permission isn't granted, it opens the
dialer (Intent.ACTION_DIAL) with the number filled in. Once the call
starts, the phone reports it through call.state, so the PC's call card
and in-call controls work as for any call.
With sim (an id from call.sims, 1 to 64 bytes), a phone that offers
call.sims places the call on that SIM, or on its default if the SIM is
gone; phones from before sim ignore it. A PC sends sim only to a phone
that offers call.sims.
Errors: DENIED when calls are off for the PC, UNSUPPORTED when the
phone doesn't offer call.dial, INTERNAL when the phone couldn't start
the call.
2.4.1 call.sims
call.sims asks which SIMs (and calling apps, such as a SIP account) the
phone places calls with: at most 8, each with an id that stays the same
while the SIM is in and a label as Android shows it ("SIM 1 · Airtel"),
and default when the phone calls with one without asking. A phone set to
ask each time has no default, and Android would ask on the phone, where
nobody at the PC sees it, so the PC picks one: the user's choice for that
phone, else the first. With one SIM there's nothing to pick.
Errors: DENIED when calls are off for the PC, UNSUPPORTED when the
phone doesn't offer call.sims.
2.5 On Android
call.control needs the phone permission and the permission to answer
calls. call.log needs the call log permission. call.dial uses
CALL_PHONE to place the call directly, or opens the dialer when
CALL_PHONE isn't granted. call.sims needs CALL_PHONE and
READ_PHONE_STATE: it lists TelecomManager.getCallCapablePhoneAccounts()
and calls with EXTRA_PHONE_ACCOUNT_HANDLE. call.incall needs Android 12 or later and
the MANAGE_ONGOING_CALLS app-op, which lets Telecom bind NectarLink's
in-call service as a calling companion without it being the phone app.
Apps can't grant that app-op to themselves; NectarLink's Elevated mode
(Wireless debugging) grants it through the shell when it starts.
Not in this service:
- Recording calls. Android doesn't let apps other than the phone's own record call audio (capturing the voice call stream needs a privileged permission), so NectarLink doesn't offer it.
- Talking through the PC. Carrying the call's audio to the PC's microphone and speakers is planned as a Bluetooth hands-free (HFP) link from the PC to the phone, as for a headset; it isn't part of this service.
3. Privacy
Numbers, names and photos are never logged (v0 §11).