Push notifications

ChatProvider runs push for the signed-in session on its own: it reads /push/config, asks for permission, registers the FCM token (re-registers on refresh), shows foreground notifications, clears notifications when a conversation is opened, and routes taps (conversation → room, thread → room + thread, ringing call → incoming-call UI) from foreground, background and killed states. logoutChatSession() deletes the tokens server-side.

Host steps

Firebase + APNs — Firebase, APNs & backend setup and the native files in Native configuration.
index.js — configurePushNotifications(...) and the background handlers (App entry).
Your own listeners skip RealtimeX pushes and forward the launch notification:

typescript

1import {extractPushData, isRealtimexPush, openRealtimexNotification} from '@realtimexsco/live-chat-react-native';2 3// onMessage / onNotificationOpenedApp4if (isRealtimexPush(extractPushData(remoteMessage))) return;5 6// cold start7messaging().getInitialNotification().then(message => {8  if (message && isRealtimexPush(extractPushData(message))) {9    openRealtimexNotification(extractPushData(message));10  }11});

Chat inside a tab — bring the tab forward in onNotificationOpened; the package opens the room once the chat stack is mounted.

configurePushNotifications options

Option	Default	Purpose
`androidFullScreenCalls`	`false` (`registerRealtimexBackgroundHandler` sets it `true` when Notifee is installed)	Register with payload version 2 → ringing calls arrive data-only and show as full-screen Notifee notifications
`iosVoipCalls`	`true`	Register the PushKit token when the client has a VoIP key (needs CallKeep + VoIP push + the `voip` background mode)
`apnsEnvironment`	`sandbox` in `__DEV__`, else `production`	PushKit token environment
`inAppBanner`	`true`	In-app banner (toast `notification`) for foreground notifications; also the fallback without Notifee
`foregroundSystemNotifications`	`false`	Show foreground notifications (socket event or push, whichever arrives first, once) as Notifee system notifications instead of the banner
`onForegroundNotification(notification)`	—	Called before a foreground notification is shown (plain-text `title` / `body`); return `true` to show it yourself
`androidSmallIcon`	Notifee's `ic_launcher`	Icon for notifications the package draws
`onNotificationOpened(target)`	—	Called before the package navigates. `target`: `{type:'conversation', conversationId, isGroup?}` \| `{type:'thread', conversationId, threadRootId, isGroup?}` \| `{type:'call', callId, conversationId?}`

Settings UI

NotificationSettingsScreen (header bell) — master switch; direct / groups / threads / calls; preview; quiet hours; admin-locked rows. Per-conversation level and mute are in the room menu (roomOptions.notifications). Muted and mentions-only conversations show an icon in the list.

Other exports: registerPushForSession, unregisterPushForSession, startRealtimexNotifications, startRealtimexVoip (iOS — configurePushNotifications already calls it), subscribeNotificationPrefs, handleRealtimexForegroundMessage, NotificationsApiError, apiGetPushConfig, apiGetNotificationPreferences, apiPatchNotificationPreferences, apiGetConversationNotifications, apiPutConversationNotifications.

How push behaves in each app state

Moment	Behavior
Foreground	In-app banner from the `notification` socket event, or from the push while the socket is down (skipped for the open conversation / thread and for calls). Tap opens it. With `foregroundSystemNotifications: true` (needs Notifee) it is a system notification instead, shown once
Background / killed	OS notification; `action: clear` pushes close the one with that `tag`
Tap	`threadRootId` → room + thread, else `conversationId` → room; ringing call → incoming-call screen if still ringing. Taps that cold-start the app wait for sign-in and the chat navigator
Opening a conversation	Its notifications and banner are cleared; `presence_focus` tells the server
Settings	`NotificationSettingsScreen` (header bell) and the room menu's Notifications (level + mute)

Only RealtimeX pushes are handled (data with userId and a RealtimeX category, or action: clear with a tag). Other pushes pass through to your app untouched. A push for a different signed-in user is dropped.

Android full-screen incoming calls

With @notifee/react-native installed and androidFullScreenCalls: true:

A ringing call arrives data-only and the package draws a full-screen notification on the rtx_calls channel with Accept / Decline.
It rings and vibrates until Accept, Decline, a clear / missed push, or the 40-second ring ends.
Accept opens the app, asks for the microphone (and camera for video) and joins. Decline rejects without opening the app, even when it was killed.
The notification is drawn natively by the autolinked RtxCallPushReceiver the moment FCM delivers the push, so it shows even before JavaScript starts.
Both setBackgroundMessageHandler and notifee.onBackgroundEvent must be registered in index.js, or killed-app rings and Decline won't run.
Samsung and other OEM battery managers can block FCM: when testing, keep the app out of "Sleeping apps" and set battery usage to "Unrestricted". "Force stop" blocks FCM until the app is opened again.

iOS calls over PushKit + CallKit

When the client admin uploads an Apple VoIP key (/push/config returns voipConfigured: true):

Install react-native-voip-push-notification and react-native-callkeep, then pod install.
Add the Push Notifications capability and the voip + remote-notification background modes.
That's all on the native side: the autolinked RealtimexVoip (ios/RealTimeXChat/RealtimexVoip.m) sets up CallKit and PushKit at launch and reports every VoIP push to CallKit.
configurePushNotifications(...) in index.js attaches the CallKit listeners, so a call that relaunched the app is answered or declined before ChatProvider mounts.

The package ends the ringing CallKit call when the session doesn't match, the push expired, the call is no longer ringing, the caller cancels, the call is answered on another device, or a clear / missed push arrives. In the foreground the in-app overlay rings instead of CallKit.