dpearson2699/swift-ios-skills / skills/callkit
callkit
VerifiedImplement VoIP calling with CallKit and PushKit. Use when building incoming/outgoing call flows, registering for VoIP push notifications, configuring CXProvider and CXCallController, handling call actions, coordinating audio sessions, or creating Call Directory extensions for caller ID and call blocking.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.5 KB |
| evals/evals.json | config | 4.4 KB |
| references/callkit-patterns.md | markdown | 12.4 KB |
references/callkit-patterns.md
View on GitHub# CallKit + PushKit Extended Patterns
Overflow reference for the `callkit` skill. Contains advanced patterns that exceed the main skill file's scope.
## Contents
- [Full Call Manager](#full-call-manager)
- [Hold and Mute Actions](#hold-and-mute-actions)
- [Multiple Concurrent Calls](#multiple-concurrent-calls)
- [Call State Tracking](#call-state-tracking)
- [Encrypted VoIP Push Filtering](#encrypted-voip-push-filtering)
- [Call Directory Incremental Updates](#call-directory-incremental-updates)
- [Testing VoIP Locally](#testing-voip-locally)
## Full Call Manager
```swift
import CallKit
import AVFoundation
import PushKit
@Observable
@MainActor
final class VoIPCallManager: NSObject {
let provider: CXProvider
let callController = CXCallController()
private(set) var activeCalls: [UUID: CallInfo] = [:]
struct CallInfo {
let uuid: UUID
let handle: String
let isOutgoing: Bool
var isOnHold: Bool = false
var isMuted: Bool = false
var isConnected: Bool = false
}
override init() {
let config = CXProviderConfiguration()
config.localizedName = "My VoIP"
config.supportsVideo = true
config.maximumCallGroups = 2
config.maximumCallsPerCallGroup = 1
config.supportedHandleTypes = [.phoneNumber]
config.includesCallsInRecents = true
provider = CXProvider(configuration: config)
super.init()
provider.setDelegate(self, queue: nil)
}
// MARK: - Incoming
func reportIncoming(
uuid: UUID,
handle: String,
callerName: String,
hasVideo: Bool
) async throws {
let update = CXCallUpdate()
update.remoteHandle = CXHandle(type: .phoneNumber, value: handle)
update.localizedCallerName = callerName
update.hasVideo = hasVideo
update.supportsHolding = true
update.supportsDTMF = true
update.supportsGrouping = false
update.supportsUngrouping = false
try await withCheckedThrowingContinuation {
(continuation: CheckedContinuation<Void, Error>) in
provider.reportNewIncomingCall(
with: uuid, update: update
) { error in
if let error {
continuation.resume(throwing: error)
} else {
continuation.resume()
}
}
}
activeCalls[uuid] = CallInfo(
uuid: uuid, handle: handle, isOutgoing: false
)
}
// MARK: - Outgoing
func startCall(handle: String, hasVideo: Bool) {
let uuid = UUID()
let cxHandle = CXHandle(type: .phoneNumber, value: handle)
let action = CXStartCallAction(call: uuid, handle: cxHandle)
action.isVideo = hasVideo
callController.request(
CXTransaction(action: action)
) { error in
if let error {
print("Start call failed: \(error)")
}
}
activeCalls[uuid] = CallInfo(
uuid: uuid, handle: handle, isOutgoing: true
)
}
// MARK: - Actions
func endCall(uuid: UUID) {
let action = CXEndCallAction(call: uuid)
callController.request(CXTransaction(action: action)) { error in
if let error { print("End call failed: \(error)") }
}
}
func setHeld(uuid: UUID, onHold: Bool) {
let action = CXSetHeldCallAction(call: uuid, onHold: onHold)
callController.request(CXTransaction(action: action)) { error in
if let error { print("Hold failed: \(error)") }
}
}
func setMuted(uuid: UUID, muted: Bool) {
let action = CXSetMutedCallAction(call: uuid, muted: muted)
callController.request(CXTransaction(action: action)) { error in
if let error { print("Mute failed: \(error)") }
}
}
}
```
## Hold and Mute Actions
```swift
extension VoIPCallManager: CXProviderDelegate {
nonisolated func providerDidReset(_ provider: CXProvider) {
Task { @MainActor in
for uuid in activeCalls.keys {
disconnectCall(uuid)
}
activeCalls.removeAll()
}
}
nonisolated func provider(
_ provider: CXProvider,
perform action: CXSetHeldCallAction
) {
Task { @MainActor in
activeCalls[action.callUUID]?.isOnHold = action.isOnHold
if action.isOnHold {
pauseAudio(for: action.callUUID)
} else {
resumeAudio(for: action.callUUID)
}
action.fulfill()
}
}
nonisolated func provider(
_ provider: CXProvider,
perform action: CXSetMutedCallAction
) {
Task { @MainActor in
activeCalls[action.callUUID]?.isMuted = action.isMuted
// If call translation is active, mute app input without deactivating
// upstream audio that translated audio may need.
setMicrophoneMuted(action.isMuted)
action.fulfill()
}
}
nonisolated func provider(
_ provider: CXProvider,
perform action: CXAnswerCallAction
) {
Task { @MainActor in
configureAudioSession()
connectToServer(callUUID: action.callUUID) { success in
if success {
activeCalls[action.callUUID]?.isConnected = true
action.fulfill()
} else {
provider.reportCall(
with: action.callUUID,
endedAt: Date(),
reason: .failed
)
action.fail()
}
}
}
}
nonisolated func provider(
_ provider: CXProvider,
perform action: CXStartCallAction
) {
Task { @MainActor in
configureAudioSession()
provider.reportOutgoingCall(
with: action.callUUID,
startedConnectingAt: Date()
)
connectToServer(callUUID: action.callUUID)
provider.reportOutgoingCall(
with: action.callUUID,
connectedAt: Date()
)
activeCalls[action.callUUID]?.isConnected = true
action.fulfill()
}
}
nonisolated func provider(
_ provider: CXProvider,
perform action: CXEndCallAction
) {
Task { @MainActor in
disconnectCall(action.callUUID)
activeCalls.removeValue(forKey: action.callUUID)
action.fulfill()
}
}
nonisolated func provider(
_ provider: CXProvider,
didActivate audioSession: AVAudioSession
) {
Task { @MainActor in
startAudioEngine()
}
}
nonisolated func provider(
_ provider: CXProvider,
didDeactivate audioSession: AVAudioSession
) {
Task { @MainActor in
stopAudioEngine()
}
}
}
```
## Multiple Concurrent Calls
When a second call arrives while one is active, CallKit automatically puts
the first call on hold. Handle the hold action to pause your audio stream:
```swift
nonisolated func provider(
_ provider: CXProvider,
perform action: CXSetHeldCallAction
) {
Task { @MainActor in
if action.isOnHold {
// Pause the RTP stream for this call
pauseMediaStream(for: action.callUUID)
} else {
// Resume the RTP stream
resumeMediaStream(for: action.callUUID)
}
activeCalls[action.callUUID]?.isOnHold = action.isOnHold
action.fulfill()
}
}
```
Configure `maximumCallGroups` and `maximumCallsPerCallGroup` in
`CXProviderConfiguration` to control how many concurrent calls your app
supports.
## Call State Tracking
Use `CXCallObserver` to monitor call state changes from outside the provider
delegate:
```swift
import CallKit
final class CallStateObserver: NSObject, CXCallObserverDelegate {
let observer = CXCallObserver()
override init() {
super.init()
observer.setDelegate(self, queue: nil)
}
func callObserver(
_ callObserver: CXCallObserver,
callChanged call: CXCall
) {
if call.hasEnded {
print("Call \(call.uuid) ended")
} else if call.hasConnected {
print("Call \(call.uuid) connected")
} else if call.isOutgoing {
print("Outgoing call \(call.uuid) ringing")
} else {
print("Incoming call \(call.uuid) ringing")
}
}
}
```
## Encrypted VoIP Push Filtering
Use a notification service extension with
`CXProvider.reportNewIncomingVoIPPushPayload` only when server-side metadata
encryption means the server cannot determine whether the outgoing notification
is a VoIP call request or some other data. If the server knows the content is
a VoIP call, send a normal PushKit VoIP push instead.
```swift
import UserNotifications
import CallKit
final class NotificationService: UNNotificationServiceExtension {
override func didReceive(
_ request: UNNotificationRequest,
withContentHandler contentHandler:
@escaping (UNNotificationContent) -> Void
) {
guard let encryptedPayload = request.content
.userInfo["encrypted"] as? [AnyHashable: Any] else {
contentHandler(request.content)
return
}
let decryptedPayload = decryptPayload(encryptedPayload)
CXProvider.reportNewIncomingVoIPPushPayload(
decryptedPayload
) { error in
if let error {
// Show a missed-call notification instead
let content = UNMutableNotificationContent()
content.title = "Missed Call"
content.body = decryptedPayload["callerName"] as? String ?? ""
contentHandler(content)
} else {
// Call was reported; suppress the notification
contentHandler(UNNotificationContent())
}
}
}
}
```
This requires the `com.apple.developer.usernotifications.filtering` entitlement.
## Call Directory Incremental Updates
After the first full load, use incremental updates to add or remove entries
without reloading the entire dataset:
```swift
private func addOrRemoveIncrementalEntries(
to context: CXCallDirectoryExtensionContext
) {
let removedNumbers: [CXCallDirectoryPhoneNumber] = fetchRemovedNumbers()
for number in removedNumbers {
context.removeBlockingEntry(withPhoneNumber: number)
context.removeIdentificationEntry(withPhoneNumber: number)
}
let newBlocked: [CXCallDirectoryPhoneNumber] = fetchNewBlockedNumbers()
for number in newBlocked.sorted() {
context.addBlockingEntry(withNextSequentialPhoneNumber: number)
}
let newIdentified: [(CXCallDirectoryPhoneNumber, String)] = fetchNewIdentified()
for (number, label) in newIdentified.sorted(by: { $0.0 < $1.0 }) {
context.addIdentificationEntry(
withNextSequentialPhoneNumber: number,
label: label
)
}
}
```
Call Directory data is bulk data. The system calls `beginRequest(with:)` when
loading the extension, not for each individual incoming call, so keep web
lookups and dataset sync in the containing app before reloading the extension.
## Testing VoIP Locally
### Simulating VoIP Pushes
Use the Push Notifications Console or a command-line tool to send test pushes.
The payload must target the VoIP topic (`<bundle-id>.voip`):
```json
{
"aps": {},
"handle": "+15551234567",
"callerName": "Test Caller",
"hasVideo": false
}
```
### Testing Without a Server
For development, you can bypass PushKit and directly call the incoming call
reporting method:
```swift
#if DEBUG
func simulateIncomingCall() {
let uuid = UUID()
Task {
try? await CallManager.shared.reportIncomingCall(
uuid: uuid,
handle: "+15551234567",
hasVideo: false
)
}
}
#endif
```
### Checking Extension Status
Verify that the Call Directory extension is enabled:
```swift
CXCallDirectoryManager.sharedInstance.getEnabledStatusForExtension(
withIdentifier: "com.example.app.CallDirectory"
) { status, error in
switch status {
case .enabled:
print("Extension is enabled")
case .disabled:
print("Extension is disabled -- prompt user to enable in Settings")
case .unknown:
print("Status unknown")
@unknown default:
break
}
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |