REACT NATIVE • PUSH NOTIFICATIONS • GUIDE

React Native incoming call notification when the app is closed

To make a React Native app ring like WhatsApp when it is closed or the phone is locked, your calling server sends a high-priority Firebase (FCM) data message, a background handler in index.js shows a full-screen notification with a looping ringtone and Answer/Decline buttons, and a second push stops the ringing when the caller hangs up. This guide shows the complete Android setup with @react-native-firebase/messaging and @notifee/react-native, tested on real phones with the app in the background, swiped away and on a locked screen.

Why the app can't ring by itself

When your app is closed, its JavaScript isn't running, so it can't keep a connection open to hear about calls. Only Google's push service can wake an Android phone. The flow is:

  1. The caller taps Call. Your calling server sees that the other user is offline.
  2. The server sends a high-priority data message through Firebase Cloud Messaging to that user's phone.
  3. Android wakes your app's background handler, which shows the ringing notification.
  4. On Answer, the app opens, connects and joins the call. If the caller hangs up first, the server sends another push and the app stops ringing.
Use data messages, not notification messagesA notification message is shown by Android itself as a normal one-beep notification, and your code may not run at all. A data message always reaches your background handler, so you control the ringing screen.

1. Install and set up Firebase

Create a Firebase project, add your Android app with its exact package name, and put google-services.json in android/app/ (see the React Native Firebase setup). Then install:

npm install @react-native-firebase/app @react-native-firebase/messaging @notifee/react-native @react-native-async-storage/async-storage

Add the permissions for notifications and the full-screen ringing screen, and let the activity show over the lock screen:

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />
<uses-permission android:name="android.permission.VIBRATE" />

<activity android:name=".MainActivity"
  android:showWhenLocked="true"
  android:turnScreenOn="true" ... />

On Android 13 and newer, ask for the notification permission at runtime (PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS or notifee.requestPermission()).

2. Register the phone with your calling server

Each phone has an FCM token. Send it to whatever server starts the calls, after the user signs in and whenever the token changes. With RTCExpress that is one request with the user's RTC token:

import messaging from "@react-native-firebase/messaging";

// After the user signs in: tell your calling server where to send call pushes
async function registerForCalls(userToken) {
  const fcmToken = await messaging().getToken();
  await fetch("https://api.devsquarelabs.com/v1/push/devices", {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: `Bearer ${userToken}` },
    body: JSON.stringify({ installationId: await getSavedDeviceId(), platform: "android", token: fcmToken }),
  });
}

// FCM tokens change sometimes: register again when they do
messaging().onTokenRefresh(() => getUserToken().then(registerForCalls));

With RTCExpress you also upload your Firebase service-account key once in the console, so it can send pushes to your app. Details: push notification docs.

3. Ring with a full-screen notification

Register the background handler in index.js, outside any component, so it runs even when the app is swiped away. The pushes below use RTCExpress's payload (rtc_call_invite with callId, roomId, fromUserId, callType and expiresAt); with your own server, use the same idea with your own fields.

// index.js: this runs even when the app is swiped away
import { AppRegistry } from "react-native";
import messaging from "@react-native-firebase/messaging";
import notifee, { AndroidCategory, AndroidImportance, AndroidVisibility, EventType } from "@notifee/react-native";
import AsyncStorage from "@react-native-async-storage/async-storage";
import App from "./App";

async function showIncomingCall(call) {
  await notifee.createChannel({
    id: "incoming_calls", name: "Incoming calls",
    importance: AndroidImportance.HIGH, visibility: AndroidVisibility.PUBLIC,
    sound: "default", vibration: true,
  });
  await notifee.displayNotification({
    id: `call-${call.callId}`,
    title: call.fromUserId,
    body: call.callType === "video" ? "Incoming video call" : "Incoming voice call",
    data: { ...call, kind: "call" },
    android: {
      channelId: "incoming_calls",
      category: AndroidCategory.CALL,
      importance: AndroidImportance.HIGH,
      ongoing: true,          // can't be swiped away while ringing
      loopSound: true,        // keep ringing, not one short beep
      timeoutAfter: Math.max(5000, Number(call.expiresAt) - Date.now()),
      fullScreenAction: { id: "default" },  // ringing screen on a locked phone
      pressAction: { id: "default", launchActivity: "default" },
      actions: [
        { title: "Answer", pressAction: { id: "answer", launchActivity: "default" } },
        { title: "Decline", pressAction: { id: "decline" } },
      ],
    },
  });
}

messaging().setBackgroundMessageHandler(async ({ data }) => {
  if (data?.type === "rtc_call_invite") await showIncomingCall(data);
  // Caller hung up, or nobody answered: stop ringing
  if (data?.type === "rtc_call_cancel" || data?.type === "rtc_missed_call") {
    await notifee.cancelNotification(`call-${data.callId}`);
  }
});

notifee.onBackgroundEvent(async ({ type, detail }) => {
  const call = detail.notification?.data;
  if (type !== EventType.ACTION_PRESS || call?.kind !== "call") return;
  await notifee.cancelNotification(`call-${call.callId}`);
  if (detail.pressAction?.id === "answer") await AsyncStorage.setItem("answerCallId", String(call.callId));
});

AppRegistry.registerComponent("YourApp", () => App);
  • loopSound + ongoing make it ring until answered, declined or timed out, instead of one beep.
  • timeoutAfter stops the ringing when the call expires (60 seconds with RTCExpress), so a phone that comes online late doesn't ring for an old call.
  • fullScreenAction shows the ringing screen on a locked phone. On Android 14+, the full-screen permission is granted automatically only to calling and alarm apps; check it with notifee.getNotificationSettings().

4. Stop ringing when the caller hangs up

This is the part most tutorials skip, and it's why some apps keep ringing after the caller has given up. The server has to send a second push when the call stops ringing, and the app cancels the notification with the same ID. RTCExpress sends rtc_call_cancel (caller hung up, declined, or answered on another device) and rtc_missed_call (nobody answered). The handler above already handles both. Add missed calls to your own Calls list if you have one.

5. Answer the call

Tapping Answer opens the app. Connect with a fresh token and accept the call that was ringing:

// App.tsx: the app was opened by tapping "Answer"
import RTCExpress from "rtcexpress-react-native";

const rtc = new RTCExpress();
const answerId = await AsyncStorage.getItem("answerCallId");

rtc.on("callInvite", (invite) => {
  if (invite.callId === answerId) {
    AsyncStorage.removeItem("answerCallId");
    rtc.acceptCall();                // straight into the call
  } else {
    showIncomingCallScreen(invite);  // app was already open: your own ringing UI
  }
});

// Connect with a fresh token. A call that is still ringing is delivered again
// as a callInvite event as soon as the app connects.
await rtc.init({ serverUrl: "https://api.devsquarelabs.com", appId, userId, token: await getUserToken() });

While the app is open, you don't need the push at all: the SDK's callInvite event fires over the live connection, and you show your own in-app ringing screen.

Test checklist

  • Test on real phones, not an emulator, with the app in the background, swiped away, and with the screen locked.
  • Caller hangs up while it's ringing: the other phone stops ringing and shows a missed call.
  • Nobody answers for 60 seconds: ringing stops by itself.
  • Sign out: unregister the device (DELETE /v1/push/devices/<id> with RTCExpress), so the old user's calls stop ringing that phone.
  • Try a Xiaomi, Oppo or Vivo phone too: their battery savers can block background apps until the user allows it.

Frequently asked questions

Can a React Native app ring when it is closed?

Yes, on Android, with a high-priority Firebase Cloud Messaging data message. Firebase wakes a small part of your JavaScript (the background handler in index.js), which shows a full-screen call notification with notifee. The rest of the app only starts when the user taps Answer.

Why does my call notification only beep once?

Normal notifications play their sound once. For a ringing call, set loopSound: true and ongoing: true, use the CALL category, and give the call channel its own sound. Android never changes the sound of an existing notification channel, so if you change it, create a channel with a new ID.

Why don't I get the push when the app is swiped away?

Make sure the server sends a data message (not a notification message) with high priority, and that the background handler is registered in index.js, outside any React component. Some phones (Xiaomi, Oppo, Vivo, some Samsung settings) stop background apps aggressively; ask users to allow the app to run in the background.

How do I stop the ringing when the caller hangs up?

The calling server must send a second push when the call stops ringing. RTCExpress sends rtc_call_cancel when the caller hangs up or the call is answered elsewhere, and rtc_missed_call when nobody answers. Cancel the notification with the same ID in both cases.

What about iPhone?

iOS does not let apps show their own ringing screen. Incoming calls must arrive as a VoIP push through PushKit and be reported to CallKit straight away, which shows the system call screen. Libraries such as react-native-callkeep and react-native-voip-push-notification wrap these APIs.

Calling that already sends the pushes

RTCExpress runs the call server, TURN relay and push delivery for you: start with a free trial of 1:1 voice and chat, with group calls from $9/month.

Create free accountReact Native voice calling tutorial