Push-to-wake works on Android. iOS needs PushKit and CallKit, which the SDK doesn’t support yet: on iOS the app rings only while it is open.
How it works
- A call rings a SIP user whose app isn’t connected. Vobiz holds the call for up to 30 seconds and pushes every device registered for that SIP user.
- Your app receives the push, shows a call screen, and hands the push to the SDK with
handleIncomingPush. - The SDK claims the call: its next REGISTER carries the push’s hold reference, and Vobiz sends the held call to this phone.
- The call arrives as a normal incoming call. If the user already tapped Accept, the SDK answers at once.
Before you start
- Firebase. Create a Firebase project, add your Android app, put
google-services.jsoninandroid/app/, and addfirebase_coreandfirebase_messagingto your app. - Vobiz push credential. In the Vobiz Console, open Voice > Push Notifications and add your Firebase project’s credential for your app. Vobiz sends incoming-call pushes through Firebase with it.
- A call screen. A plugin such as
flutter_callkit_incomingshows the full-screen incoming-call UI on a locked phone. See the manifest changes it needs. - A SIP user to push. Pushes target the SIP username the app signs in as (
client.sipUsername).
Register the device
Register the phone with Vobiz after the user signs in, and again whenever its Firebase token changes. Remove it at sign-out.Signature
register sends POST https://api.vobiz.ai/api/v1/devices/register, and logout sends DELETE https://api.vobiz.ai/api/v1/devices/logout. Both throw VobizException (push_device_failed) with Vobiz’s message when the request is refused.
Stay reachable after Android closes the app
The SDK registers for an hour at a time (Expires: 3600) and renews while the app runs. When Android closes the app without signing out, Vobiz keeps the registration until it expires, and calls in that time take the push path. Each time the user opens the app, the SDK registers again for another hour.
A sign-out with client.disconnect() removes the registration, so call devices.logout too: a signed-out phone shouldn’t ring.
Receive the push
VobizIncomingPush.tryParse reads a push’s data map, such as RemoteMessage.data. It returns null for anything that isn’t a call push.
Signature
handleIncomingPush starts the claim. Signed in and registered, the claiming REGISTER goes at once; otherwise the next sign-in carries it, so sign in right after. It returns false and does nothing for a push that isn’t a call Vobiz holds, is a test, or has expired. The same push handled twice returns true and does nothing more.
A Vobiz push looks like this (Firebase delivers every value as a string):
Foreground and background
Handle the push in both places Firebase delivers it:Accept or decline from the call screen
Report the call screen’s buttons to the SDK. A call accepted, or declined, before it arrives is answered, or declined, as soon as it does.Signature
When the user taps Accept while the app is closed, Android opens it. Hand the accepted push to the SDK before you sign in, so the sign-in’s REGISTER claims the call:
Follow the pushed call
pushCallUpdates reports each step of a pushed call:
Each
VobizPushCallUpdate has push, status, and callId (the SDK’s call ID once the call has arrived).
client.isPushedCall(callId) tells you whether an incoming call came through push, and client.pushedCall returns the push being handled.
Test push-to-wake
- Sign in on a real Android phone and register the device.
- Close the app without signing out:
client.disconnect(unregister: false)simulates Android closing it. - Call the phone’s SIP user, for example with the Voice API to
sip:YOUR_SIP_USERNAME@registrar.vobiz.ai, or a number whose application dials<User>. - The call screen should appear within a few seconds. Tap Accept.
Limits
- Android only. iOS isn’t supported yet.
- 30-second hold. If the app can’t claim the call in time, the caller hears the call fail.
- Device registration credentials. Vobiz’s device API takes account credentials today; register devices from your backend in production.
- One registration per SIP user. Give each phone its own SIP user: the newest sign-in replaces the previous one.