Definition

Reporting an incoming call means informing CallKit that an external call event has arrived so iOS can present the native incoming call UI.

In CallKit, this is done using:

provider.reportNewIncomingCall(with: uuid, update: update)

Core Concept

Incoming calls originate outside the app, usually from:

• VoIP push notification
• backend signaling event
• WebSocket event
• SIP/WebRTC signaling layer

Your app does not ask the system to start the call.

Instead, it tells the system:

“A new incoming call exists.”

Basic Flow

External call event
        ↓
App creates UUID
        ↓
App creates CXCallUpdate
        ↓
App reports incoming call
        ↓
iOS shows native incoming call UI

Code Example

func reportIncomingCall(from caller: String) {
    let uuid = UUID()

    let update = CXCallUpdate()
    update.remoteHandle = CXHandle(
        type: .phoneNumber,
        value: caller
    )
    update.localizedCallerName = caller
    update.hasVideo = false

    provider.reportNewIncomingCall(with: uuid, update: update) { error in
        if let error = error {
            print("Failed to report incoming call:", error.localizedDescription)
        } else {
            print("Incoming call reported successfully")
        }
    }
}