---
title: "How do I troubleshoot iOS CallKit integration issues?"
topic: "Troubleshooting"
updated: 2026-05-06
canonical: https://acrobits.net/resources/knowledge-base/ios-callkit-softphone/
summary: "Common CallKit issues include missing native call screens, push not waking the app, dual-app conflicts, and Bluetooth audio routing problems. Cloud Softphone handles CallKit integration automatically."
---

# How do I troubleshoot iOS CallKit integration issues?

> Common CallKit issues include missing native call screens, push not waking the app, dual-app conflicts, and Bluetooth audio routing problems. Cloud Softphone handles CallKit integration automatically.

The four most common iOS CallKit issues are: missing native call screens, push not waking the app, dual-app conflicts, and Bluetooth audio routing failures. Each has a distinct cause and fix.

## Issue 1: App Doesn't Show the Native Call Screen

**Symptom:** Incoming calls arrive (you can see them in logs) 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 being triggered within the required timeframe. Since iOS 13, Apple requires that every PushKit VoIP notification presents a CallKit call screen within ~3 seconds. If the app fails to do this, 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 with a real device — CallKit does not work in the iOS Simulator.

## Issue 2: Push Not Waking 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 — check the SIPIS dashboard first before debugging certificates. 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 app or restored from backup — 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.

## Issue 3: 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's call screen blocks the other.

**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.

  - If a subscriber must use two VoIP apps, configure them with different SIP accounts.

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

## Issue 4: 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 — behavior varies between AirPods, car systems, and third-party headsets.

## Cloud Softphone Handles This Automatically

Cloud Softphone includes full CallKit integration out of the box — push certificate management, audio session handling, and call screen presentation. Operators don't need to debug these issues because the platform handles the Apple-specific requirements with every iOS update.

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 CallKit issues include missing native call screens, push not waking the app, dual-app conflicts, and Bluetooth audio routing problems. Cloud Softphone handles CallKit integration automatically."
      }
    }
  ]
}