@telnyx/react-voice-commons-sdk 0.1.7 → 0.1.8-beta.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # CHANGELOG.md
 
+## [0.1.8-beta.1](https://github.com/team-telnyx/react-native-voice-commons/releases/tag/0.1.8-beta.1) (2026-03-04)
+
+### Bug Fixing
+
+• Fixed duplicate CXProvider overwrite causing `CXEndCallAction` error 4 (unknownCallUUID) — guard `setupCallKit()` to prevent async `setupAutomatically()` from overwriting the provider created by `setupSynchronously()` during VoIP push handling
+• Fixed intermittent audio loss on push notification calls — defer `CXAnswerCallAction.fulfill()` until `reportCallConnected()` when the WebRTC peer connection is ready
+• Aligned iOS audio session handling with native Telnyx iOS SDK pattern (`RTCAudioSessionConfiguration.webRTC()` with `lockForConfiguration`/`unlockForConfiguration`)
+• Fixed endCall not dismissing CallKit UI — check `endCall()` return value and fallback to `reportCallEnded()` when CXEndCallAction fails
+• Fixed push notification answer crash when voipClient is not yet initialized — defer to `checkForInitialPushNotification()` instead of failing the call
+• Added `voipClient.queueAnswerFromCallKit()` call when handling push notification answer for auto-answer on INVITE arrival
+
 ## [0.1.7](https://github.com/team-telnyx/react-native-voice-commons/releases/tag/0.1.7) (2026-02-20)
 
 ### Enhancement

package/README.md

@@ -32,15 +32,30 @@ The `@telnyx/react-voice-commons-sdk` library provides:
 Integrate the library using the `TelnyxVoiceApp` component for automatic lifecycle management:
 
 ```tsx
-import { TelnyxVoiceApp, createTelnyxVoipClient } from '@telnyx/react-voice-commons-sdk';
+import {
+  TelnyxVoiceApp,
+  TelnyxVoipClient,
+  createTelnyxVoipClient,
+} from '@telnyx/react-voice-commons-sdk';
 
-// Create the VoIP client instance
+// Create the VoIP client instance (singleton — safe to call inside a component body)
 const voipClient = createTelnyxVoipClient({
   enableAppStateManagement: true, // Optional: Enable automatic app state management (default: true)
   debug: true, // Optional: Enable debug logging
 });
 
 export default function App() {
+  // Skip auto-login if the app was launched from a push notification —
+  // the SDK handles login internally via the push notification flow.
+  React.useEffect(() => {
+    TelnyxVoipClient.isLaunchedFromPushNotification().then((isFromPush) => {
+      if (!isFromPush) {
+        // Safe to auto-login
+        voipClient.loginFromStoredConfig();
+      }
+    });
+  }, []);
+
   return (
     <TelnyxVoiceApp voipClient={voipClient} enableAutoReconnect={false} debug={true}>
       <YourAppContent />
@@ -54,10 +69,16 @@ export default function App() {
 ### 1. VoIP Client Configuration
 
 ```tsx
+// createTelnyxVoipClient is a singleton — repeated calls return the same instance.
+// This makes it safe to call inside a React component body without re-creating on every render.
 const voipClient = createTelnyxVoipClient({
   enableAppStateManagement: true, // Optional: Enable automatic app state management (default: true)
   debug: true, // Optional: Enable debug logging
 });
+
+// If you need to tear down and recreate the client (e.g., on logout):
+import { destroyTelnyxVoipClient } from '@telnyx/react-voice-commons-sdk';
+destroyTelnyxVoipClient(); // Disposes the singleton; next createTelnyxVoipClient() call creates a fresh instance
 ```
 
 **Configuration Options Explained:**
@@ -73,6 +94,7 @@ The `TelnyxVoiceApp` component handles:
 - Push notification processing from terminated state
 - Login state management with automatic reconnection
 - Background client management for push notifications
+- **Automatic CallKit coordinator wiring** — the `voipClient` is set on the CallKit coordinator on mount, so you don't need to call `setVoipClient()` manually
 
 ### 3. Reactive State Management
 
@@ -416,9 +438,18 @@ npx expo run:ios
 
 ### Common Integration Issues
 
-### Double Login
+### Double Login on Cold-Start
+
+When the app is launched from a push notification, the SDK handles login internally. If your app also auto-logs in on mount, both will race and the push flow breaks. Use `isLaunchedFromPushNotification()` to guard your auto-login:
+
+```tsx
+const isFromPush = await TelnyxVoipClient.isLaunchedFromPushNotification();
+if (!isFromPush) {
+  voipClient.loginFromStoredConfig();
+}
+```
 
-Ensure you're not calling login methods manually when using `TelnyxVoiceApp` with auto-reconnection enabled.
+Also ensure you're not calling login methods manually when using `TelnyxVoiceApp` with auto-reconnection enabled.
 
 ### Background Disconnection
 
@@ -457,7 +488,6 @@ useEffect(() => {
   const subscription = voipClient.connectionState$.subscribe(handleStateChange);
   return () => subscription.unsubscribe();
 }, []);
-}, []);
 ```
 
 ## Documentation

package/ios/CallKitBridge.swift

@@ -205,6 +205,33 @@ import React
             }
 
             provider.reportOutgoingCall(with: uuid, connectedAt: Date())
+
+            // Fulfill deferred CXAnswerCallAction now that peer connection is ready
+            if let pendingAction = manager.pendingAnswerAction {
+                NSLog("TelnyxVoice: reportCallConnected - fulfilling deferred CXAnswerCallAction")
+                pendingAction.fulfill()
+                manager.pendingAnswerAction = nil
+            } else {
+                // Fallback: ensure audio is enabled for non-push or already-fulfilled cases
+                let rtcAudioSession = RTCAudioSession.sharedInstance()
+                rtcAudioSession.lockForConfiguration()
+                let webRTCConfig = RTCAudioSessionConfiguration.webRTC()
+                webRTCConfig.categoryOptions = [.duckOthers, .allowBluetooth]
+                do {
+                    try rtcAudioSession.setConfiguration(webRTCConfig)
+                } catch {
+                    NSLog("TelnyxVoice: reportCallConnected - setConfiguration error: \(error)")
+                }
+                do {
+                    try rtcAudioSession.setActive(true)
+                } catch {
+                    NSLog("TelnyxVoice: reportCallConnected - setActive error: \(error)")
+                }
+                rtcAudioSession.isAudioEnabled = true
+                rtcAudioSession.unlockForConfiguration()
+                rtcAudioSession.audioSessionDidActivate(AVAudioSession.sharedInstance())
+            }
+
             resolve(["success": true])
         }
 
@@ -276,6 +303,7 @@ import React
         public var callKitProvider: CXProvider?
         public var callKitController: CXCallController?
         public var activeCalls: [UUID: [String: Any]] = [:]
+        public var pendingAnswerAction: CXAnswerCallAction?
 
         private override init() {
             super.init()
@@ -327,12 +355,16 @@ import React
         }
 
         private func setupCallKit() {
-            // CRITICAL: Configure WebRTC for manual audio control BEFORE CallKit setup
+            // ALWAYS configure WebRTC audio, even if provider already exists
             RTCAudioSession.sharedInstance().useManualAudio = true
-            RTCAudioSession.sharedInstance().isAudioEnabled = false  // MUST be false initially!
-            NSLog(
-                "🎧 TelnyxVoice: WebRTC configured for manual audio control (audio DISABLED until CallKit activates)"
-            )
+            RTCAudioSession.sharedInstance().isAudioEnabled = false
+
+            // Guard against duplicate provider creation (async setupAutomatically can overwrite
+            // the provider created by setupSynchronously for VoIP push)
+            guard callKitProvider == nil else {
+                NSLog("TelnyxVoice: setupCallKit() - provider already exists, skipping to prevent overwrite")
+                return
+            }
 
             // Use the localizedName from the app's bundle display name or fallback
             let appName =
@@ -351,11 +383,7 @@ import React
             callKitProvider?.setDelegate(self, queue: nil)
             callKitController = CXCallController()
 
-            NSLog(
-                "📞 TelnyxVoice: CallKit provider instance: \(String(describing: callKitProvider))")
-            NSLog(
-                "📞 TelnyxVoice: CallKit controller instance: \(String(describing: callKitController))"
-            )
+            NSLog("TelnyxVoice: CallKit provider and controller created")
         }
 
      
@@ -519,9 +547,9 @@ import React
                     callData: activeCalls[action.callUUID])
             }
 
-            NSLog("📞 TelnyxVoice: Fulfilling CXAnswerCallAction for call UUID: \(action.callUUID)")
-            action.fulfill()
-            NSLog("📞 TelnyxVoice: ✅ CXAnswerCallAction fulfilled successfully")
+            // Defer action.fulfill() until reportCallConnected when peer connection is ready
+            NSLog("TelnyxVoice: Deferring CXAnswerCallAction.fulfill() until peer connection is ready")
+            self.pendingAnswerAction = action
         }
 
         public func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
@@ -552,58 +580,67 @@ import React
         }
 
         public func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
-            NSLog(
-                "🎧🎧🎧 TelnyxVoice: AUDIO SESSION ACTIVATED BY CALLKIT - USER ANSWERED THE CALL! 🎧🎧🎧")
-            NSLog("🎧 Provider: \(provider)")
+            NSLog("TelnyxVoice: Audio session activated by CallKit")
 
+            let rtcAudioSession = RTCAudioSession.sharedInstance()
 
-            // CRITICAL: Activate WebRTC audio session 
-            RTCAudioSession.sharedInstance().audioSessionDidActivate(audioSession)
-            RTCAudioSession.sharedInstance().isAudioEnabled = true
-            NSLog("🎧 TelnyxVoice: WebRTC RTCAudioSession activated and audio enabled")
-
+            // Step 1: Configure (matches native iOS SDK setupCorrectAudioConfiguration)
+            rtcAudioSession.lockForConfiguration()
+            let webRTCConfig = RTCAudioSessionConfiguration.webRTC()
+            webRTCConfig.categoryOptions = [.duckOthers, .allowBluetooth]
             do {
-                // Configure audio session for VoIP with proper routing
-                try audioSession.setCategory(
-                    .playAndRecord, mode: .voiceChat,
-                    options: [.allowBluetooth, .allowBluetoothA2DP])
-                try audioSession.setActive(true)
-
-                // Emit audio session activated event to React Native
-                CallKitBridge.shared?.emitAudioSessionEvent(
-                    "AudioSessionActivated",
-                    data: [
-                        "category": audioSession.category.rawValue,
-                        "mode": audioSession.mode.rawValue,
-                        "isActive": true,
-                    ])
-
-                NSLog(
-                    "🎧 SUCCESS: Audio session ACTIVE for VoIP - Category: \(audioSession.category.rawValue), Mode: \(audioSession.mode.rawValue)"
-                )
+                try rtcAudioSession.setConfiguration(webRTCConfig)
             } catch {
-                NSLog("❌ FAILED: Audio session configuration error: \(error)")
+                NSLog("TelnyxVoice: didActivateAudioSession - setConfiguration error: \(error)")
+            }
+            rtcAudioSession.unlockForConfiguration()
 
-                // Emit audio session failed event to React Native
-                CallKitBridge.shared?.emitAudioSessionEvent(
-                    "AudioSessionFailed",
-                    data: [
-                        "error": error.localizedDescription
-                    ])
+            // Step 2: Activate (matches native iOS SDK setAudioSessionActive)
+            rtcAudioSession.lockForConfiguration()
+            do {
+                try rtcAudioSession.setActive(true)
+            } catch {
+                NSLog("TelnyxVoice: didActivateAudioSession - setActive error: \(error)")
             }
+            rtcAudioSession.isAudioEnabled = true
+            rtcAudioSession.unlockForConfiguration()
+
+            rtcAudioSession.audioSessionDidActivate(audioSession)
+
+            // Emit audio session activated event to React Native
+            CallKitBridge.shared?.emitAudioSessionEvent(
+                "AudioSessionActivated",
+                data: [
+                    "category": audioSession.category.rawValue,
+                    "mode": audioSession.mode.rawValue,
+                    "isActive": true,
+                ])
         }
 
         public func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
-            NSLog("🔇🔇🔇 TelnyxVoice: AUDIO SESSION DEACTIVATED BY CALLKIT 🔇🔇🔇")
-            NSLog("🔇 Provider: \(provider)")
-            NSLog(
-                "🔇 Audio session details: active=\(audioSession.isOtherAudioPlaying), category=\(audioSession.category.rawValue), mode=\(audioSession.mode.rawValue)"
-            )
+            NSLog("TelnyxVoice: Audio session deactivated by CallKit")
 
-            // CRITICAL: Deactivate WebRTC audio session (matches Flutter implementation)
-            RTCAudioSession.sharedInstance().audioSessionDidDeactivate(audioSession)
-            RTCAudioSession.sharedInstance().isAudioEnabled = false
-            NSLog("🔇 TelnyxVoice: WebRTC RTCAudioSession deactivated and audio disabled")
+            let rtcAudioSession = RTCAudioSession.sharedInstance()
+
+            // Reset audio config (matches native iOS SDK resetAudioConfiguration)
+            let avAudioSession = AVAudioSession.sharedInstance()
+            do {
+                try avAudioSession.setCategory(.playback, mode: .default, options: [.mixWithOthers])
+            } catch {
+                NSLog("TelnyxVoice: didDeactivateAudioSession - setCategory error: \(error)")
+            }
+
+            // Deactivate (matches native iOS SDK setAudioSessionActive(false))
+            rtcAudioSession.lockForConfiguration()
+            do {
+                try rtcAudioSession.setActive(false)
+            } catch {
+                NSLog("TelnyxVoice: didDeactivateAudioSession - setActive(false) error: \(error)")
+            }
+            rtcAudioSession.isAudioEnabled = false
+            rtcAudioSession.unlockForConfiguration()
+
+            rtcAudioSession.audioSessionDidDeactivate(audioSession)
 
             // Emit audio session deactivated event to React Native
             CallKitBridge.shared?.emitAudioSessionEvent(

package/lib/callkit/callkit-coordinator.js

@@ -228,21 +228,26 @@ class CallKitCoordinator {
       'CallKitCoordinator: Ending call from UI - dismissing CallKit and hanging up WebRTC call',
       callKitUUID
     );
-    // Mark as processing to prevent duplicate actions
-    this.processingCalls.add(callKitUUID);
+    // Track this call as ended to prevent duplicate end actions
+    this.endedCalls.add(callKitUUID);
     try {
-      // End the call in CallKit and hang up the WebRTC call
-      await callkit_1.default.endCall(callKitUUID);
+      // End the call in CallKit - endCall returns false on failure (doesn't throw)
+      const endCallSuccess = await callkit_1.default.endCall(callKitUUID);
+      if (!endCallSuccess) {
+        // Fallback: use reportCallEnded to dismiss CallKit UI when endCall fails
+        // (e.g., unknownCallUUID error from duplicate CXProvider)
+        await callkit_1.default.reportCallEnded(callKitUUID, callkit_1.CallEndReason.RemoteEnded);
+      }
+      this.isCallFromPush = false;
       call.hangup();
-      // Clean up the mappings
       this.cleanupCall(callKitUUID);
       return true;
     } catch (error) {
       console.error('CallKitCoordinator: Error ending call from UI', error);
-      call.hangup(); // Ensure WebRTC call is ended
+      this.isCallFromPush = false;
+      call.hangup();
+      this.cleanupCall(callKitUUID);
       return false;
-    } finally {
-      this.processingCalls.delete(callKitUUID);
     }
   }
   /**
@@ -303,10 +308,21 @@ class CallKitCoordinator {
       } else {
         console.log('CallKitCoordinator: Outgoing call, skipping answer and CONNECTING state');
       }
+      // Clear push data now that answer action is fulfilled
+      try {
+        await voice_pn_bridge_1.VoicePnBridge.clearPendingVoipPush();
+        console.log('CallKitCoordinator: Cleared pending VoIP push after answer fulfilled');
+      } catch (clearErr) {
+        console.error('CallKitCoordinator: Error clearing push data after answer:', clearErr);
+      }
     } catch (error) {
       console.error('CallKitCoordinator: Error processing CallKit answer', error);
       await callkit_1.default.reportCallEnded(callKitUUID, callkit_1.CallEndReason.Failed);
       this.cleanupCall(callKitUUID);
+      // Clear push data even on error to prevent stale state
+      try {
+        await voice_pn_bridge_1.VoicePnBridge.clearPendingVoipPush();
+      } catch (_) {}
     } finally {
       this.processingCalls.delete(callKitUUID);
     }
@@ -352,6 +368,11 @@ class CallKitCoordinator {
     } finally {
       this.processingCalls.delete(callKitUUID);
       this.cleanupCall(callKitUUID);
+      // Clear push data now that end action is fulfilled
+      try {
+        await voice_pn_bridge_1.VoicePnBridge.clearPendingVoipPush();
+        console.log('CallKitCoordinator: Cleared pending VoIP push after end fulfilled');
+      } catch (_) {}
       // Check if app is in background and no more calls - disconnect client
       await this.checkBackgroundDisconnection();
     }
@@ -456,18 +477,22 @@ class CallKitCoordinator {
         // Set auto-answer flag so when the WebRTC call comes in, it will be answered automatically
         this.shouldAutoAnswerNextCall = true;
         console.log('CallKitCoordinator: ✅ Set auto-answer flag for next incoming call');
-        // Get VoIP client and trigger reconnection
+        // Try to get VoIP client - it may not be wired yet if user answered
+        // from CallKit before React Native finished initializing
         const voipClient = this.getSDKClient();
         if (!voipClient) {
-          console.error(
-            'CallKitCoordinator: ❌ No VoIP client available - cannot reconnect for push notification'
-          );
-          await callkit_1.default.reportCallEnded(callKitUUID, callkit_1.CallEndReason.Failed);
-          this.cleanupCall(callKitUUID);
+          // voipClient not ready yet - DON'T fail the call.
+          // shouldAutoAnswerNextCall is already set to true above.
+          // checkForInitialPushNotification() will run after setVoipClient()
+          // and will find the push data still intact, call handleCallKitPushReceived()
+          // which checks shouldAutoAnswerNextCall and queues the auto-answer.
           return;
         }
+        // voipClient is available - queue the answer action on the TelnyxRTC client
+        // so when the INVITE arrives after WebSocket login, processInvite() sees
+        // pendingAnswerAction=true and auto-answers the call.
+        voipClient.queueAnswerFromCallKit();
         // Get the real push data that was stored by the VoIP push handler
-        console.log('CallKitCoordinator: 🔍 Getting real push data from VoicePnBridge...');
         let realPushData = null;
         try {
           const pendingPushJson = await voice_pn_bridge_1.VoicePnBridge.getPendingVoipPush();
@@ -506,6 +531,11 @@ class CallKitCoordinator {
         // Set the pending push action to be handled when app comes to foreground
         await voice_pn_bridge_1.VoicePnBridge.setPendingPushAction(pushAction, pushMetadata);
         console.log('CallKitCoordinator: ✅ Set pending push action');
+        // Clear push data now that push notification answer is handled
+        try {
+          await voice_pn_bridge_1.VoicePnBridge.clearPendingVoipPush();
+          console.log('CallKitCoordinator: Cleared pending VoIP push after push answer handled');
+        } catch (_) {}
         return;
       }
       // For other platforms (shouldn't happen on iOS)
@@ -533,6 +563,11 @@ class CallKitCoordinator {
         this.voipClient.queueEndFromCallKit();
         // Clean up push notification state
         await this.cleanupPushNotificationState();
+        // Clear push data now that rejection is handled
+        try {
+          await voice_pn_bridge_1.VoicePnBridge.clearPendingVoipPush();
+          console.log('CallKitCoordinator: Cleared pending VoIP push after rejection handled');
+        } catch (_) {}
         console.log('CallKitCoordinator: 🎯 Push notification rejection handling complete');
         return;
       }
@@ -561,16 +596,11 @@ class CallKitCoordinator {
           if (!this.connectedCalls.has(callKitUUID)) {
             console.log('CallKitCoordinator: WebRTC call active - reporting connected to CallKit');
             try {
-              // Report as connected (CallKit call already answered in UI flow)
               await callkit_1.default.reportCallConnected(callKitUUID);
-              console.log(
-                'CallKitCoordinator: Call reported as connected to CallKit ',
-                callKitUUID
-              );
-              this.connectedCalls.add(callKitUUID);
             } catch (error) {
               console.error('CallKitCoordinator: Error reporting call connected:', error);
             }
+            this.connectedCalls.add(callKitUUID);
           }
           break;
         case 'ended':
@@ -738,7 +768,11 @@ class CallKitCoordinator {
    * This helps prevent premature flag resets during CallKit operations
    */
   hasProcessingCalls() {
-    return this.processingCalls.size > 0;
+    // Also return true when isCallFromPush is set — this prevents the
+    // calls$ subscription in TelnyxVoiceApp from resetting protection flags
+    // (isHandlingForegroundCall, backgroundDetectorIgnore) before the WebRTC
+    // call arrives during push notification handling.
+    return this.processingCalls.size > 0 || this.isCallFromPush;
   }
   /**
    * Check if there's currently a call from push notification being processed

package/lib/telnyx-voice-app.js

@@ -274,8 +274,14 @@ const TelnyxVoiceAppComponent = ({
           return null;
         }
         log('Found pending VoIP push data:', voipPayload);
-        await VoicePnBridge.clearPendingVoipPush();
-        log('Cleared pending VoIP push data after retrieval');
+        // Do NOT clear push data here. Let it persist until the answer/end action
+        // is fulfilled in the CallKit coordinator. This prevents a race condition in
+        // Expo apps where the RN bridge mounts immediately on push notification —
+        // the push data would be consumed and cleared before the user answers,
+        // leaving the coordinator with nothing to work with.
+        // For non-Expo apps (RN mounts after answer), the coordinator's
+        // handlePushNotificationAnswer/Reject clears the data before
+        // checkForInitialPushNotification ever runs, so no loop occurs.
         return { action: 'incoming_call', metadata: voipPayload.metadata, from_notification: true };
       } catch (parseError) {
         log('Error parsing VoIP push JSON:', parseError);
@@ -315,11 +321,17 @@ const TelnyxVoiceAppComponent = ({
           return;
         }
         log('Processing initial push notification...');
-        // Prevent duplicate processing if already connected
+        // Prevent duplicate processing if already connected or connecting.
+        // Since push data is no longer cleared on read, this guard prevents
+        // re-processing when checkForInitialPushNotification fires again on app resume.
         if (
-          voipClient.currentConnectionState === connection_state_1.TelnyxConnectionState.CONNECTED
+          voipClient.currentConnectionState ===
+            connection_state_1.TelnyxConnectionState.CONNECTED ||
+          voipClient.currentConnectionState === connection_state_1.TelnyxConnectionState.CONNECTING
         ) {
-          log('SKIPPING - Already connected, preventing duplicate processing');
+          log(
+            `SKIPPING - Already ${voipClient.currentConnectionState}, preventing duplicate processing`
+          );
           return;
         }
         // Set flags to prevent auto-reconnection during push call

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telnyx/react-voice-commons-sdk",
-  "version": "0.1.7",
+  "version": "0.1.8-beta.1",
   "description": "A high-level, state-agnostic, drop-in module for the Telnyx React Native SDK that simplifies WebRTC voice calling integration",
   "main": "lib/index.js",
   "module": "lib/index.js",

package/src/callkit/callkit-coordinator.ts

@@ -218,24 +218,30 @@ class CallKitCoordinator {
       callKitUUID
     );
 
-    // Mark as processing to prevent duplicate actions
-    this.processingCalls.add(callKitUUID);
+    // Track this call as ended to prevent duplicate end actions
+    this.endedCalls.add(callKitUUID);
 
     try {
-      // End the call in CallKit and hang up the WebRTC call
-      await CallKit.endCall(callKitUUID);
-      call.hangup();
+      // End the call in CallKit - endCall returns false on failure (doesn't throw)
+      const endCallSuccess = await CallKit.endCall(callKitUUID);
 
-      // Clean up the mappings
+      if (!endCallSuccess) {
+        // Fallback: use reportCallEnded to dismiss CallKit UI when endCall fails
+        // (e.g., unknownCallUUID error from duplicate CXProvider)
+        await CallKit.reportCallEnded(callKitUUID, CallEndReason.RemoteEnded);
+      }
+
+      this.isCallFromPush = false;
+      call.hangup();
       this.cleanupCall(callKitUUID);
 
       return true;
     } catch (error) {
       console.error('CallKitCoordinator: Error ending call from UI', error);
-      call.hangup(); // Ensure WebRTC call is ended
+      this.isCallFromPush = false;
+      call.hangup();
+      this.cleanupCall(callKitUUID);
       return false;
-    } finally {
-      this.processingCalls.delete(callKitUUID);
     }
   }
 
@@ -306,10 +312,21 @@ class CallKitCoordinator {
       } else {
         console.log('CallKitCoordinator: Outgoing call, skipping answer and CONNECTING state');
       }
+      // Clear push data now that answer action is fulfilled
+      try {
+        await VoicePnBridge.clearPendingVoipPush();
+        console.log('CallKitCoordinator: Cleared pending VoIP push after answer fulfilled');
+      } catch (clearErr) {
+        console.error('CallKitCoordinator: Error clearing push data after answer:', clearErr);
+      }
     } catch (error) {
       console.error('CallKitCoordinator: Error processing CallKit answer', error);
       await CallKit.reportCallEnded(callKitUUID, CallEndReason.Failed);
       this.cleanupCall(callKitUUID);
+      // Clear push data even on error to prevent stale state
+      try {
+        await VoicePnBridge.clearPendingVoipPush();
+      } catch (_) {}
     } finally {
       this.processingCalls.delete(callKitUUID);
     }
@@ -366,6 +383,12 @@ class CallKitCoordinator {
       this.processingCalls.delete(callKitUUID);
       this.cleanupCall(callKitUUID);
 
+      // Clear push data now that end action is fulfilled
+      try {
+        await VoicePnBridge.clearPendingVoipPush();
+        console.log('CallKitCoordinator: Cleared pending VoIP push after end fulfilled');
+      } catch (_) {}
+
       // Check if app is in background and no more calls - disconnect client
       await this.checkBackgroundDisconnection();
     }
@@ -489,19 +512,24 @@ class CallKitCoordinator {
         this.shouldAutoAnswerNextCall = true;
         console.log('CallKitCoordinator: ✅ Set auto-answer flag for next incoming call');
 
-        // Get VoIP client and trigger reconnection
+        // Try to get VoIP client - it may not be wired yet if user answered
+        // from CallKit before React Native finished initializing
         const voipClient = this.getSDKClient();
         if (!voipClient) {
-          console.error(
-            'CallKitCoordinator: ❌ No VoIP client available - cannot reconnect for push notification'
-          );
-          await CallKit.reportCallEnded(callKitUUID, CallEndReason.Failed);
-          this.cleanupCall(callKitUUID);
+          // voipClient not ready yet - DON'T fail the call.
+          // shouldAutoAnswerNextCall is already set to true above.
+          // checkForInitialPushNotification() will run after setVoipClient()
+          // and will find the push data still intact, call handleCallKitPushReceived()
+          // which checks shouldAutoAnswerNextCall and queues the auto-answer.
           return;
         }
 
+        // voipClient is available - queue the answer action on the TelnyxRTC client
+        // so when the INVITE arrives after WebSocket login, processInvite() sees
+        // pendingAnswerAction=true and auto-answers the call.
+        voipClient.queueAnswerFromCallKit();
+
         // Get the real push data that was stored by the VoIP push handler
-        console.log('CallKitCoordinator: 🔍 Getting real push data from VoicePnBridge...');
         let realPushData = null;
         try {
           const pendingPushJson = await VoicePnBridge.getPendingVoipPush();
@@ -544,6 +572,12 @@ class CallKitCoordinator {
         await VoicePnBridge.setPendingPushAction(pushAction, pushMetadata);
         console.log('CallKitCoordinator: ✅ Set pending push action');
 
+        // Clear push data now that push notification answer is handled
+        try {
+          await VoicePnBridge.clearPendingVoipPush();
+          console.log('CallKitCoordinator: Cleared pending VoIP push after push answer handled');
+        } catch (_) {}
+
         return;
       }
 
@@ -577,6 +611,12 @@ class CallKitCoordinator {
         // Clean up push notification state
         await this.cleanupPushNotificationState();
 
+        // Clear push data now that rejection is handled
+        try {
+          await VoicePnBridge.clearPendingVoipPush();
+          console.log('CallKitCoordinator: Cleared pending VoIP push after rejection handled');
+        } catch (_) {}
+
         console.log('CallKitCoordinator: 🎯 Push notification rejection handling complete');
         return;
       }
@@ -609,17 +649,11 @@ class CallKitCoordinator {
             console.log('CallKitCoordinator: WebRTC call active - reporting connected to CallKit');
 
             try {
-              // Report as connected (CallKit call already answered in UI flow)
               await CallKit.reportCallConnected(callKitUUID);
-              console.log(
-                'CallKitCoordinator: Call reported as connected to CallKit ',
-                callKitUUID
-              );
-
-              this.connectedCalls.add(callKitUUID);
             } catch (error) {
               console.error('CallKitCoordinator: Error reporting call connected:', error);
             }
+            this.connectedCalls.add(callKitUUID);
           }
           break;
 
@@ -815,7 +849,11 @@ class CallKitCoordinator {
    * This helps prevent premature flag resets during CallKit operations
    */
   hasProcessingCalls(): boolean {
-    return this.processingCalls.size > 0;
+    // Also return true when isCallFromPush is set — this prevents the
+    // calls$ subscription in TelnyxVoiceApp from resetting protection flags
+    // (isHandlingForegroundCall, backgroundDetectorIgnore) before the WebRTC
+    // call arrives during push notification handling.
+    return this.processingCalls.size > 0 || this.isCallFromPush;
   }
 
   /**

package/src/telnyx-voice-app.tsx

@@ -374,8 +374,14 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
 
         log('Found pending VoIP push data:', voipPayload);
 
-        await VoicePnBridge.clearPendingVoipPush();
-        log('Cleared pending VoIP push data after retrieval');
+        // Do NOT clear push data here. Let it persist until the answer/end action
+        // is fulfilled in the CallKit coordinator. This prevents a race condition in
+        // Expo apps where the RN bridge mounts immediately on push notification —
+        // the push data would be consumed and cleared before the user answers,
+        // leaving the coordinator with nothing to work with.
+        // For non-Expo apps (RN mounts after answer), the coordinator's
+        // handlePushNotificationAnswer/Reject clears the data before
+        // checkForInitialPushNotification ever runs, so no loop occurs.
 
         return { action: 'incoming_call', metadata: voipPayload.metadata, from_notification: true };
       } catch (parseError) {
@@ -424,9 +430,14 @@ const TelnyxVoiceAppComponent: React.FC<TelnyxVoiceAppProps> = ({
 
         log('Processing initial push notification...');
 
-        // Prevent duplicate processing if already connected
-        if (voipClient.currentConnectionState === TelnyxConnectionState.CONNECTED) {
-          log('SKIPPING - Already connected, preventing duplicate processing');
+        // Prevent duplicate processing if already connected or connecting.
+        // Since push data is no longer cleared on read, this guard prevents
+        // re-processing when checkForInitialPushNotification fires again on app resume.
+        if (
+          voipClient.currentConnectionState === TelnyxConnectionState.CONNECTED ||
+          voipClient.currentConnectionState === TelnyxConnectionState.CONNECTING
+        ) {
+          log(`SKIPPING - Already ${voipClient.currentConnectionState}, preventing duplicate processing`);
           return;
         }