---
title: "How do I troubleshoot iOS CallKit integration issues?"
topic: "Troubleshooting"
updated: 2026-07-09
canonical: https://acrobits.net/resources/knowledge-base/ios-callkit-softphone/
summary: "Common iOS CallKit issues fall into four areas: the app not showing the native call screen, VoIP push not waking the app, dual-app conflicts, and Bluetooth audio routing failures. The fastest first checks are to confirm the app calls reportNewIncomingCall the moment a PushKit notification arrives, that the VoIP push certificate is valid and actually delivering, and that you are testing on a real device rather than the Simulator. Each issue, its cause, and its fix are below."
---

# How do I troubleshoot iOS CallKit integration issues?

> Common iOS CallKit issues fall into four areas: the app not showing the native call screen, VoIP push not waking the app, dual-app conflicts, and Bluetooth audio routing failures. The fastest first checks are to confirm the app calls reportNewIncomingCall the moment a PushKit notification arrives, that the VoIP push certificate is valid and actually delivering, and that you are testing on a real device rather than the Simulator. Each issue, its cause, and its fix are below.

Common iOS CallKit issues fall into four areas: the app not showing the native call screen, VoIP push not waking the app, dual-app conflicts, and Bluetooth audio routing failures. The fastest first checks are to confirm the app calls reportNewIncomingCall the moment a PushKit notification arrives, that the VoIP push certificate is valid and actually delivering, and that you are testing on a real device rather than the Simulator. Each issue, its cause, and its fix are below.

## App doesn't show the native call screen

**Symptom:** Incoming calls arrive but the iPhone doesn't display the green/red answer screen. The app may show its own custom UI, or nothing at all.

**Cause:** CallKit is either not configured or not triggered in time. Since iOS 13, Apple has required every PushKit VoIP notification to present a CallKit call screen within about three seconds; if the app misses that window, iOS terminates it.

**Fix:**

  - Verify that CXProvider is configured and reportNewIncomingCall is called immediately upon receiving the PushKit callback.

  - Check that the CallKit entitlement is enabled in your app's provisioning profile.

  - Test on a real device, since CallKit is not available in the iOS Simulator.

## Push does not wake the app

**Symptom:** Calls ring on other devices but the iPhone never wakes up. No call screen, no notification, nothing in logs.

**Cause:** The APNs [VoIP push](/voip-glossary/voip-push/) is not reaching the device. If you are using Cloud Softphone, push delivery runs through [SIPIS](/voip-glossary/sipis/), Acrobits' push infrastructure (operational since 2009), which works regardless of your softswitch. Start with the SIPIS dashboard, then verify certificates if delivery is still failing. Common reasons for delivery failure:

  
    CauseHow to Check
  
  
    Expired push certificateCheck Apple Developer portal: VoIP Services certificates expire annually
    Wrong push typeMust use PushKit (VoIP type), not standard APNs
    Stale device tokenUser reinstalled the app or restored from backup, so the token changed
    Sandbox vs production mismatchDevelopment cert won't work with production APNs gateway
  

**Fix:**

  - Regenerate the VoIP Services certificate in the Apple Developer portal and update your push server.

  - Confirm you're using the correct APNs environment (sandbox for development builds, production for App Store/TestFlight).

  - Implement token refresh handling so stale tokens are replaced automatically.

## Dual-app CallKit conflicts

**Symptom:** Subscriber has two VoIP apps installed (e.g., your branded app and another SIP client). Incoming calls show on the wrong app, or one app can win the race to present the call screen.

**Cause:** iOS allows multiple apps to register with CallKit, but only one call can be active at a time. If both apps receive a push for the same SIP account, they race to present the call screen.

**Fix:**

  - Each app should use a unique SIP registration. Two apps registered to the same SIP account on the same device will always conflict.

  - When two VoIP apps must coexist on one device, give them different SIP accounts.

  - Use CallKit's CXCallDirectoryExtension to manage caller ID without conflicting with the other app's call handling.

## Bluetooth audio routing problems

**Symptom:** Subscriber answers a call but audio stays on the iPhone speaker instead of routing to their connected Bluetooth headset. Or audio switches mid-call.

**Cause:** CallKit manages audio sessions. If the app creates its own AVAudioSession configuration that conflicts with CallKit's, audio routing breaks. This is especially common with Bluetooth devices that support both HFP (calls) and A2DP (media).

**Fix:**

  - Do not manually configure AVAudioSession category or mode before CallKit's provider:didActivateAudioSession: callback fires.

  - Let CallKit activate the audio session first, then configure your SIP audio engine.

  - Test with multiple Bluetooth devices, since behavior varies between AirPods, car systems, and third-party headsets.

## Cloud Softphone handles this automatically

Cloud Softphone includes CallKit integration, push certificate management, audio session handling, and call screen presentation. Operators don't need to debug these issues because the platform is built to absorb Apple-specific requirement changes across iOS updates.

If you're seeing CallKit issues on a custom-built app and want to stop fighting iOS updates, [explore Cloud Softphone](/cloud-softphone/). The equivalent platform challenge on the other side is [background ringing on Android](/resources/knowledge-base/sip-background-ringing-android/), where Doze mode and OEM battery managers create their own delivery problems.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "How do I troubleshoot iOS CallKit integration issues?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Common iOS CallKit issues fall into four areas: the app not showing the native call screen, VoIP push not waking the app, dual-app conflicts, and Bluetooth audio routing failures. The fastest first checks are to confirm the app calls reportNewIncomingCall the moment a PushKit notification arrives, that the VoIP push certificate is valid and actually delivering, and that you are testing on a real device rather than the Simulator. Each issue, its cause, and its fix are below."
      }
    }
  ]
}