Skip to main content
When Android closes your app, its connection to Vobiz closes too. Vobiz push-to-wake still rings it: Vobiz holds the incoming call, sends a push to the user’s phone, and hands the call to the app once it wakes up and claims it.
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

  1. 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.
  2. Your app receives the push, shows a call screen, and hands the push to the SDK with handleIncomingPush.
  3. The SDK claims the call: its next REGISTER carries the push’s hold reference, and Vobiz sends the held call to this phone.
  4. The call arrives as a normal incoming call. If the user already tapped Accept, the SDK answers at once.
The app must claim the call within the 30-second hold, so start signing in as soon as the push arrives.

Before you start

  • Firebase. Create a Firebase project, add your Android app, put google-services.json in android/app/, and add firebase_core and firebase_messaging to 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_incoming shows 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.
Vobiz’s device registration takes your account X-Auth-ID and X-Auth-Token (VobizPushDevices.accountHeaders). That’s fine for testing, but the Auth Token is your account’s API key and must not ship in an app. In production, register devices from your backend: the app sends its token to your server, and your server calls the device API. authHeaders also accepts whatever credentials Vobiz introduces for apps.

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:
Then sign in as usual. The REGISTER claims the held call, and the SDK answers it when it arrives.

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

  1. Sign in on a real Android phone and register the device.
  2. Close the app without signing out: client.disconnect(unregister: false) simulates Android closing it.
  3. 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>.
  4. The call screen should appear within a few seconds. Tap Accept.
Test with a release build on a real device. A debug build’s cold start can be slow enough to miss the 30-second hold.

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.

Next steps