> ## Documentation Index
> Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Push notifications for incoming calls in the Vobiz Flutter SDK (Android)

> Ring a closed Android app with Vobiz push-to-wake: register the device with VobizPushDevices, parse the push with VobizIncomingPush, show a call screen, and let the Vobiz Flutter SDK claim and answer the held call.

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.

> [!NOTE]
>
> 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

```mermaid theme={null}
sequenceDiagram
  participant Caller
  participant Vobiz
  participant FCM as Firebase (FCM)
  participant App as Your app (vobiz_webrtc)
  Caller->>Vobiz: Call rings the SIP user
  Vobiz->>Vobiz: Hold the call (up to 30 s)
  Vobiz->>FCM: Push to the user's registered devices
  FCM->>App: incoming_call push
  App->>App: Show the call screen, sign in
  App->>Vobiz: REGISTER that claims the held call
  Vobiz->>App: The held call (INVITE)
  App->>Vobiz: Answer when the user taps Accept
```

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](https://www.vobiz.ai/docs/integrations/flutter-sdk/installation.md#call-screen-plugin-incoming-calls-in-the-background).
* **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.

```dart Signature theme={null}
VobizPushDevices({
  required FutureOr<Map<String, String>> Function() authHeaders,
  Uri? baseUrl,
  String pathPrefix = '/api/v1/devices',
  http.Client? httpClient,
  Duration timeout = const Duration(seconds: 15),
})

Future<void> register(VobizPushDevice device)
Future<void> logout(String deviceId)
static Map<String, String> accountHeaders(String authId, String authToken)
```

| `VobizPushDevice` field | Required | Description |
| - | - | - |
| `deviceId` | Yes | A stable ID for this installation, generated once and stored. |
| `pushToken` | Yes | The Firebase token from `FirebaseMessaging.instance.getToken()`. |
| `sipUsername` | Yes | The SIP username the app signs in as. Vobiz pushes a call only to devices registered for the called user. |
| `appBundleId` | Yes | Your Android package name. It must match the push credential in the Console. |
| `platform` | No | Defaults to `android`. |
| `pushType` | No | Defaults to `voip`. |
| `appVersion` | No | Your app's version. |
| `sdkVersion` | No | Pass `VobizClient.sdkVersion`. |

`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.

> [!WARNING]
>
> 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.

```dart theme={null}
import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:vobiz_webrtc/vobiz_webrtc.dart';

// Testing only: these credentials must not ship in an app.
final devices = VobizPushDevices(
  authHeaders: () => VobizPushDevices.accountHeaders('MA_XXXXXXXX', 'YOUR_AUTH_TOKEN'),
);

Future<void> registerForPush(VobizClient client, String installId) async {
  final token = await FirebaseMessaging.instance.getToken();
  if (token == null || client.sipUsername == null) return;
  await devices.register(VobizPushDevice(
    deviceId: installId,
    pushToken: token,
    sipUsername: client.sipUsername!,
    appBundleId: 'com.example.yourapp',
    sdkVersion: VobizClient.sdkVersion,
  ));
}

Future<void> unregisterFromPush(String installId) => devices.logout(installId);
```

### 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.

```dart Signature theme={null}
static VobizIncomingPush? tryParse(Map<String, Object?> data, {DateTime? receivedAt})
bool handleIncomingPush(VobizIncomingPush push)
```

`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):

```json theme={null}
{
  "type": "incoming_call",
  "call_id": "SIP_CALL_ID",
  "call_uuid": "CALL_UUID",
  "caller": "+91XXXXXXXXXX",
  "caller_number": "+91XXXXXXXXXX",
  "callee": "YOUR_SIP_USERNAME",
  "index": "HOLD_INDEX",
  "label": "HOLD_LABEL",
  "registrar": "REGISTRAR_INFO",
  "expires_at": "1762900030"
}
```

| `VobizIncomingPush` member | Description |
| - | - |
| `kind` | `VobizPushKind.incomingCall` or `callEnded`. |
| `callId` | The held call's SIP Call-ID. The incoming call arrives with this as `CallEvent.sipCallId`. |
| `callUuid` | Vobiz's CallUUID for the call. |
| `caller`, `callerNumber` | Who is calling. Show `callerNumber` on the call screen. |
| `callee` | The SIP user being called. |
| `hold` | The hold reference (`index`, `label`, `registrar`) the SDK sends back to claim the call. `null` for pushes that Vobiz isn't holding. |
| `isHeldByVobiz` | `true` when `hold` is present. |
| `expiresAt` | When Vobiz stops holding the call (`expires_at`, Unix seconds). |
| `isExpired([DateTime? now])` | Whether the hold has ended. |
| `matchesIncomingCall({headers, sipCallId})` | Whether an incoming call is this push's call. For a Vobiz push it compares the SIP Call-ID exactly; it never matches by phone number. |
| `isTest`, `lineBusy`, `reason`, `callKey`, `server` | Used by other push senders, such as a custom push bridge. |

### Foreground and background

Handle the push in both places Firebase delivers it:

```dart theme={null}
import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:flutter_callkit_incoming/entities/entities.dart' as ck;
import 'package:flutter_callkit_incoming/flutter_callkit_incoming.dart' as ck;
import 'package:vobiz_webrtc/vobiz_webrtc.dart';

/// Shows the system incoming-call screen for a Vobiz push.
Future<void> showCallScreen(Map<String, Object?> data) async {
  final push = VobizIncomingPush.tryParse(data);
  if (push == null || !push.isHeldByVobiz) return;
  await ck.FlutterCallkitIncoming.showCallkitIncoming(ck.CallKitParams(
    id: push.callId,
    nameCaller: push.callerNumber.isNotEmpty ? push.callerNumber : push.caller,
    appName: 'Your app',
    handle: 'Incoming call',
    type: 0,
    duration: 30000,
    extra: Map<String, dynamic>.from(data),
    android: const ck.AndroidParams(isShowFullLockedScreen: true),
  ));
}

/// Runs in a background isolate when the app is in the background or closed.
@pragma('vm:entry-point')
Future<void> onBackgroundMessage(RemoteMessage message) =>
    showCallScreen(message.data);

/// Call once at startup, in the app's main isolate.
void listenForPushes(VobizClient client) {
  FirebaseMessaging.onBackgroundMessage(onBackgroundMessage);
  FirebaseMessaging.onMessage.listen((message) async {
    final push = VobizIncomingPush.tryParse(message.data);
    if (push == null) return;
    await showCallScreen(message.data);
    client.handleIncomingPush(push); // claims at once when signed in
  });
}
```

## 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.

```dart Signature theme={null}
void reportCallScreenAccepted(VobizIncomingPush push)
void reportCallScreenDeclined(VobizIncomingPush push)
```

| Method | Effect |
| - | - |
| `reportCallScreenAccepted` | Answers the call now if it is ringing, or as soon as it arrives. A push the SDK hasn't seen yet, such as after a cold start, is handled first. |
| `reportCallScreenDeclined` | Declines the call now, or as soon as it arrives. The SDK still claims the call, so the caller hears busy at once instead of ringing out the 30-second hold. |

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:

```dart theme={null}
import 'package:flutter_callkit_incoming/entities/entities.dart' as ck;
import 'package:flutter_callkit_incoming/flutter_callkit_incoming.dart' as ck;
import 'package:vobiz_webrtc/vobiz_webrtc.dart';

VobizIncomingPush? pushFrom(ck.CallKitParams params) =>
    VobizIncomingPush.tryParse(Map<String, Object?>.from(params.extra ?? const <String, Object?>{}));

/// Call at startup, before signing in.
Future<void> handleCallScreen(VobizClient client) async {
  // Cold start: the user tapped Accept while the app was closed.
  final calls = await ck.FlutterCallkitIncoming.activeCalls();
  for (final params in calls) {
    final push = pushFrom(params);
    if (params.isAccepted == true && push != null) {
      client.reportCallScreenAccepted(push);
    }
  }

  ck.FlutterCallkitIncoming.onEvent.listen((event) {
    switch (event) {
      case ck.CallEventActionCallAccept(:final callKitParams):
        final push = pushFrom(callKitParams);
        if (push != null) client.reportCallScreenAccepted(push);
      case ck.CallEventActionCallDecline(:final callKitParams):
        final push = pushFrom(callKitParams);
        if (push != null) client.reportCallScreenDeclined(push);
      default:
        break;
    }
  });
}
```

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:

| `VobizPushCallStatus` | Meaning |
| - | - |
| `claiming` | The SDK is claiming the call. |
| `claimed` | Vobiz accepted the claim. The call follows. |
| `ringing` | The call arrived and is ringing. |
| `answering` | The call screen's Accept is being applied. |
| `declining` | The call screen's Decline is being applied. |
| `expired` | No call arrived before the hold ended. Take the call screen down. |

Each `VobizPushCallUpdate` has `push`, `status`, and `callId` (the SDK's call ID once the call has arrived).

```dart theme={null}
import 'package:flutter_callkit_incoming/flutter_callkit_incoming.dart' as ck;
import 'package:vobiz_webrtc/vobiz_webrtc.dart';

void endScreensThatExpire(VobizClient client) {
  client.pushCallUpdates.listen((update) {
    if (update.status == VobizPushCallStatus.expired) {
      ck.FlutterCallkitIncoming.endCall(update.push.callId);
    }
  });
}
```

`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](https://www.vobiz.ai/docs/call/make-call.md) 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

* [Make and receive calls](https://www.vobiz.ai/docs/integrations/flutter-sdk/calls.md)
* [Events and states](https://www.vobiz.ai/docs/integrations/flutter-sdk/events.md)
* [Installation: call-screen plugin](https://www.vobiz.ai/docs/integrations/flutter-sdk/installation.md#call-screen-plugin-incoming-calls-in-the-background)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.