public final class VoipPush

Ringing when the app is not running.

A VoIP push is a push the operating system delivers straight to the calling machinery, launching the app if it has to. It is the only way an app that is not running can make the phone ring.

VoipPush.setListener(new VoipPushListener() {
    public void callReceived(PushedCall call) {
        if (call.isStale()) { history.addMissed(call.getHandle()); return; }
        signalling.attach(call.getSession().getCallId(), call.getData());
    }
    public void tokenChanged(String token) { server.registerVoip(token); }
});
VoipPush.register();

The payload has a fixed shape, and the server must honour it

Because the call is reported to the system before any Java runs, the native code parses the push itself. It looks for one key:

{ "cn1call": { "uuid": "6B29FC40-CA47-1067-B31D-00DD010662DA",
               "handle": "+14155551212", "handleType": "phoneNumber",
               "displayName": "Jane Doe", "video": false,
               "ttl": 30, "data": "opaque, handed back untouched" } }

uuid and handle are required; the rest have defaults from the build hints. data is never parsed by the framework. Sending a payload without cn1call means the app is woken and nothing rings – on iOS, that is the case that gets the app killed.

To retract a call that was cancelled before it was answered, send the same uuid with "cancel": true.

Set the listener before registering

Calls that arrived before the app was listening are held and delivered when setListener installs one. An app that registers first and listens later still gets them – the queue is drained on the first listener – but an app that never sets a listener will find its calls timed out and ended by the platform.