CallKit

Build VoIP calling experiences that integrate with the native iOS call UI using CallKit and PushKit. Covers incoming and outgoing call flows, PushKit VoIP registration, audio session coordination, and call directory extensions. Targets Swift 6.4 / iOS 26+.

Contents

• Capabilities and Key Types
• Core Calling Architecture
• Critical VoIP Push Rule
• Audio Session Lifecycle
• Route by Task
• Common Mistakes
• Review Checklist
• References

Capabilities and Key Types

Enable Voice over IP in Signing & Capabilities > Background Modes, and add the Push Notifications capability.

Core Calling Architecture

[PushKit VoIP Push] ──> [reportNewIncomingCall] ──> [System Call UI]
                                                            │ (user answers)
                                                            ▼
[WebRTC / VoIP Stack] <── [configureAudioSession] <── [CXAnswerCallAction]

1. Maintain single CXProvider: Keep one retained CXProvider instance alive across the app lifecycle. Recreating providers disconnects active calls.
2. Handle CXProviderDelegate on serial queue: Dispatch delegate callbacks to a dedicated queue or @MainActor to prevent race conditions during call state transitions.
3. Fulfill or fail every action: Call action.fulfill() or action.fail() promptly inside delegate methods. Unfulfilled actions cause UI timeouts.

Critical VoIP Push Rule

Every VoIP push received via pushRegistry(_:didReceiveIncomingPushWith:for:) must immediately report an incoming call to CallKit via reportNewIncomingCall(with:update:completion:).

[!WARNING] Failing to report a new incoming call upon receiving a VoIP push causes iOS to terminate the app and revoke future VoIP push credentials. On iOS 26.4+, inspect PKVoIPPushMetadata to check if a push is exempt from reporting.

Audio Session Lifecycle

Do not activate the AVAudioSession during call initialization. Only configure categories in advance (.playAndRecord with .voiceChat mode). Activate the audio session only when the system invokes provider(_:didActivate:). Deactivate audio in provider(_:didDeactivate:).

Route by Task

• For a complete, observable VoIP call manager with incoming and outgoing flows, read Full Call Manager.
• For handling hold, mute, and multiple concurrent calls, read Hold and Mute Actions and Multiple Concurrent Calls.
• For encrypted VoIP push payloads and payload filtering, read Encrypted VoIP Push Filtering.
• For building Call Directory extensions (Caller ID and call blocking with incremental phone updates), read Call Directory Incremental Updates.
• For local debugging with terminal scripts and simulated push payloads, read Testing VoIP Locally.

Common Mistakes

• Receiving a VoIP push without calling reportNewIncomingCall, causing iOS to terminate the app.
• Activating AVAudioSession before the system calls provider(_:didActivate:).
• Forgetting to call action.fulfill() in CXProviderDelegate action handlers.
• Recreating CXProvider instances instead of keeping a single shared instance for the app lifecycle.
• Using standard APNs alerts for VoIP incoming calls instead of PushKit.

Review Checklist

• Voice over IP background mode and Push Notifications capabilities enabled
• Single retained CXProvider shared across the application lifetime
• Every VoIP push immediately reports an incoming call via reportNewIncomingCall
• AVAudioSession activated exclusively inside provider(_:didActivate:)
• All CXAction delegate callbacks call fulfill() or fail() promptly
• App cleanly cleans up calls when providerDidReset(_:) is triggered
• Handle types (.phoneNumber, .emailAddress, .generic) match backend identifiers
• Outgoing calls reported with reportOutgoingCall(with:startedConnectingAt:) and connectedAt:
• Call Directory extension handles incremental reload without re-inserting unchanged numbers

References

• CallKit extended patterns and Call Directory guide
• CallKit documentation
• CXProvider
• CXCallController
• PushKit documentation