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:
- The caller taps Call. Your calling server sees that the other user is offline.
- The server sends a high-priority data message through Firebase Cloud Messaging to that user's phone.
- Android wakes your app's background handler, which shows the ringing notification.
- 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.
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-storageAdd 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+ongoingmake it ring until answered, declined or timed out, instead of one beep.timeoutAfterstops the ringing when the call expires (60 seconds with RTCExpress), so a phone that comes online late doesn't ring for an old call.fullScreenActionshows 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 withnotifee.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