Luckily, Apple introduced CallKit in iOS 10 to change all that!

In this tutorial you’ll get a glimpse of CallKit’s power by building an app which:

• Uses system services to report incoming and outgoing calls.
• Manages a call directory to identify, or block incoming calls.

Getting Started

Download the starter project for this tutorial, and unzip it. In order to debug the project on your device, you’ll need to set up code signing. Open the project file in Xcode, and select Hotline in the project navigator.

You’ll start by changing the bundle identifier. With the project selected, go to the General tab, and find the Identity section. Change the bundle identifier to something unique:

Next, look for the Signing section. Select your preferred development team (in my case, it’s my personal team) in the dropdown next to Team. Also make sure, that “Automatically manage signing” is checked. This will allow Xcode to automatically create the provisioning profile for the app.

To test your setup, build and run the app on your iPhone.

This app does NOTHING!

Currently the app won’t do much, but you’ll notice that there are already quite a few source files in the starter project. They are mostly responsible for setting up the UI, and handling user interactions, but there are two main classes which are worth a look before moving on:

• Call represents a phone call. The class exposes properties for identifying calls (such as its UUID, or handle), and also lifecycle callbacks indicating when the user starts, answers or ends a call.
• CallManager currently maintains the list of ongoing calls in the app, and has methods for adding or removing calls. You will expand this class further throughout the tutorial.

What is CallKit?

CallKit is a new framework that aims to improve the VoIP experience by allowing apps to integrate tightly with the native Phone UI. By adopting CallKit, your app will be able to:

• Use the native incoming call screen in both the locked and unlocked states.
• Start calls from the native Phone app’s Contacts, Favorites and Recents screens.
• Interplay with other calls in the system.

In this section, you’ll get more familiar with the CallKit architecture. The diagram below shows all the key players:

When working with CallKit, there are two primary classes you’ll interact with: CXProvider, and CXCallController. Time to dive in!

CXProvider

Your app will use CXProvider to report any out-of-band notifications to the system. These are usually external events, such as an incoming call.

Whenever such an event occurs, CXProvider will create a call update to notify the system. What’s a call update, you ask? Call updates encapsulate new, or changed call-related information. They are represented by the CXCallUpdate class, which exposes properties such as the caller’s name, or whether it’s an audio-only, or a video call.

In turn, whenever the system wants to notify the app of any events, it does so in the form of CXAction instances. CXAction is an abstract class, which represents telephony actions. For each action, CallKit provides a different concrete implementation of CXAction. For instance, initiating an outgoing call is represented by CXStartCallAction, while CXAnswerCallAction is used for answering an incoming call. Actions are identified by a unique UUID, and can either fail, or fulfill.

Apps can communicate with CXProvider through the CXProviderDelegate protocol, which defines methods for provider lifecycle events, and incoming actions.

CXCallController

The app will use CXCallController to let the system know about any user-initiated requests, such as a “Start call” action. This is the key difference between the CXProvider and the CXCallController: while the provider’s job is to report to the system, the call controller makes requests from the system on behalf of the user.

The call controller uses transactions to make these requests. Transactions, represented by CXTransaction contain one or more CXAction instances. The call controller sends transactions to the system, and if everything is in order, the system will respond with the appropriate action to the provider.

That sure was a lot of information, but how does this work in practice?

Incoming Calls

The diagram below shows a high-level overview of an incoming call flow:

1. Whenever there’s an incoming call, the app will construct a CXCallUpdate and use the provider to send it to the system.
2. At this point the system will publish this as an incoming call to all of its services.
3. When the user answers the call, the system will send a CXAnswerCallActioninstance to the provider.
4. The app can answer the call by implementing the appropriate CXProviderDelegate method.

The first step will be creating the delegate for the provider.

Head back to Xcode, and with the App group highlighted in the project navigator, go to File\New\File…, and choose iOS\Source\Swift File. Set the name to ProviderDelegate, and click Create.

Add the following code to the file:

import AVFoundation
import CallKit

class ProviderDelegate: NSObject {
  // 1.
  fileprivate let callManager: CallManager
  fileprivate let provider: CXProvider
  
  init(callManager: CallManager) {
    self.callManager = callManager
    // 2.
    provider = CXProvider(configuration: type(of: self).providerConfiguration)
    
    super.init()
    // 3.
    provider.setDelegate(self, queue: nil)
  }
  
  // 4.
  static var providerConfiguration: CXProviderConfiguration {
    let providerConfiguration = CXProviderConfiguration(localizedName: "Hotline")
    
    providerConfiguration.supportsVideo = true
    providerConfiguration.maximumCallsPerCallGroup = 1
    providerConfiguration.supportedHandleTypes = [.phoneNumber]
    
    return providerConfiguration
  }
}

This is what’s happening:

1. The provider delegate will interact with both the provider and the call controller, so you’ll store references to both. The properties are marked fileprivate, so that you’ll be able to reach them from extensions in the same file.
2. You’ll initialize the provider with the appropriate CXProviderConfiguration, stored as a static variable below. A provider configuration specifies the behavior and capabilities of the calls.
3. To respond to events coming from the provider, you’ll set its delegate. This line will cause a build error, as ProviderDelegate doesn’t conform to CXProviderDelegate yet.
4. In the case of Hotline, the provider configuration will allow video calls, phone number handles, and restrict the number of call groups to one. For further customization, refer to the CallKit documentation.

Just below the configuration, add the following helper method:

func reportIncomingCall(uuid: UUID, handle: String, hasVideo: Bool = false, completion: ((NSError?) -> Void)?) {
  // 1.
  let update = CXCallUpdate()
  update.remoteHandle = CXHandle(type: .phoneNumber, value: handle)
  update.hasVideo = hasVideo
  
  // 2.
  provider.reportNewIncomingCall(with: uuid, update: update) { error in
    if error == nil {
      // 3.
      let call = Call(uuid: uuid, handle: handle)
      self.callManager.add(call: call)
    }
    
    // 4.
    completion?(error as? NSError)
  }
}

This helper method will allow the app to call the CXProvider API to report an incoming call. Here’s what’s going on:

1. You prepare a call update for the system, which will contain all the relevant call metadata.
2. Invoking reportIncomingCall(with:update:completion) on the provider will notify the system of the incoming call.
3. The completion handler will be called once the system processes the call. If there were no errors, you create a Call instance, and add it to the list of calls via the CallManager.
4. Invoke the completion handler, if it’s not nil.

This method can be invoked by other classes in the app in order to simulate incoming calls.

The next step is to ensure protocol conformance. Still in ProviderDelegate.swift, declare a new extension to conform to CXProviderDelegate:

extension ProviderDelegate: CXProviderDelegate {
  
  func providerDidReset(_ provider: CXProvider) {
    stopAudio()
    
    for call in callManager.calls {
      call.end()
    }
    
    callManager.removeAllCalls()
  }
}

CXProviderDelegate specifies only one required method, providerDidReset(_:). The provider invokes this method when it’s reset, giving your app the opportunity to clean up any ongoing calls, and revert to a clean state. In this implementation you’ll terminate the ongoing audio session and dispose of any active calls.

Now that ProviderDelegate offers a way to report incoming calls, it’s time to use it!

With the App group highlighted in the project navigator, open AppDelegate.swiftfor editing. You’ll start by adding a new property to the class:

lazy var providerDelegate: ProviderDelegate = ProviderDelegate(callManager: self.callManager)

The provider delegate is ready to be used! Add the following method to AppDelegate:

func displayIncomingCall(uuid: UUID, handle: String, hasVideo: Bool = false, completion: ((NSError?) -> Void)?) {
  providerDelegate.reportIncomingCall(uuid: uuid, handle: handle, hasVideo: hasVideo, completion: completion)
}

This method will let other classes access the provider delegate’s helper method.

The final piece of the puzzle is hooking up this call to the user interface. Expand the UI/View Controllers group in the project navigator, and open CallsViewController.swift, which is the controller for the main screen of the app. Find the empty implementation of unwindSegueForNewCall(_:), and replace it with the following code:

@IBAction private func unwindForNewCall(_ segue: UIStoryboardSegue) {
  // 1.
  let newCallController = segue.source as! NewCallViewController
  guard let handle = newCallController.handle else { return }
  let videoEnabled = newCallController.videoEnabled
  
  // 2.
  let backgroundTaskIdentifier = UIApplication.shared.beginBackgroundTask(expirationHandler: nil)
  DispatchQueue.main.asyncAfter(wallDeadline: DispatchWallTime.now() + 1.5) {
    AppDelegate.shared.displayIncomingCall(uuid: UUID(), handle: handle, hasVideo: videoEnabled) { _ in
      UIApplication.shared.endBackgroundTask(backgroundTaskIdentifier)
    }
  }
}

The snippet does the following:

1. You’ll extract the properties of the call from NewCallViewController, which is the source of this unwind segue.
2. The user can suspend the app before the action completes, so it should use a background task.

Now that everything is hooked up, build and run the application, and do the following:

1. Tap the plus button in the right-hand corner.
2. Enter any number, make sure “Incoming” is selected in the segmented control, and tap Done.
3. Lock the screen. This step is important, since it’s the only way to access the rich, native in-call UI.

Within a few seconds, you’ll be presented with the native incoming call UI:

It’s working!

However, as soon as you answer the call, you’ll notice that the UI remains stuck in the following state:

Or is it?

This is because you still have to implement the piece responsible for answering the call. Go back to Xcode, return to ProviderDelegate.swift, and add the following code to the class extension:

func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
  // 1.
  guard let call = callManager.callWithUUID(uuid: action.callUUID) else {
    action.fail()
    return
  }
  
  // 2.
  configureAudioSession()
  // 3.
  call.answer()
  // 4.
  action.fulfill()
}

// 5.
func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
  startAudio()
}

Here is the step-by-step breakdown:

1. You’ll start by getting a reference from the call manager, corresponding to the UUID of the call to answer.
2. It is the app’s responsibility to configure the audio session for the call. The system will take care of activating the session at an elevated priority.
3. By invoking answer(), you’ll indicate that the call is now active.
4. When processing an action, it’s important to either fail or fulfill it. If there were no errors during the process, you can call fulfill() to indicate success.
5. Once the system activates the provider’s audio session, the delegate is notified. This is your chance to begin processing the call’s audio.

Build and run the app, and start an incoming call again. When you answer the call, the system will successfully transition into an ongoing call state.

That’s more like it!

If you unlock your phone, you’ll notice that both iOS and the app now reflect the correct ongoing call state.

The ongoing call shown on the home screen, and the main screen of Hotline

Ending the Call

Answering a call reveals a new problem: there’s currently no way to end a call. The app will support two ways of ending calls: from the native in-call screen, and from within the app.

The diagram below shows what’s going on in both cases:

Notice the difference between the first step: when the user ends the call from the in-call screen (1a), the system will automatically send a CXEndCallAction to the provider. However, if you want to end a call using Hotline (1b), it’s your job to wrap the action into a transaction, and request it from the system. Once the system processes the request, it will send the CXEndCallAction back to the provider.

No matter which way you want to support ending calls, your app has to implement the necessary CXProviderDelegate method for it to work. Open ProviderDelegate.swift, and add the following implementation to the class extension:

func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
  // 1.
  guard let call = callManager.callWithUUID(uuid: action.callUUID) else {
    action.fail()
    return
  }
  
  // 2.
  stopAudio()
  // 3.
  call.end()
  // 4.
  action.fulfill()
  // 5.
  callManager.remove(call: call)
}

Not that difficult! Here’s what’s going on:

1. You start by getting a reference to the call from the call manager.
2. As the call is about to end, it’s time to stop processing the call’s audio.
3. Invoking end() changes the status of the call, allowing other classes to react to the new state.
4. At this point, you will mark the action as fulfilled.
5. Since you no longer need the call, the call manager can dispose of it.

This takes care of the in-call UI. In order to end calls from the app, you’ll need to extend CallManager. With the Call Management group expanded in the project navigator open CallManager.swift.

The call manager will communicate with CXCallController, so it will need a reference to an instance. Add the following property to the CallManager class:

private let callController = CXCallController()

Now add the following methods to the class:

func end(call: Call) {
  // 1.
  let endCallAction = CXEndCallAction(call: call.uuid)
  // 2.
  let transaction = CXTransaction(action: endCallAction)
  
  requestTransaction(transaction)
}

// 3.
private func requestTransaction(_ transaction: CXTransaction) {
  callController.request(transaction) { error in
    if let error = error {
      print("Error requesting transaction: \(error)")
    } else {
      print("Requested transaction successfully")
    }
  }
}

Here’s what’s happening:

1. You’ll start by creating an “End call” action. You’ll pass in the call’s UUID to the initializer, so it can be identified later.
2. The next step is to wrap the action into a transaction, so you can send it to the system.
3. Finally, you’ll invoke request(_:completion:) from the call controller. The system will request the provider to perform this transaction, which will in turn invoke the delegate method you just implemented.

The final step is to hook the action up to the user interface. Open CallsViewController.swift, and write the following call just below the tableView(_:cellForRowAt:) implementation:

override func tableView(_ tableView: UITableView, commit editingStyle: UITableViewCellEditingStyle, forRowAt indexPath: IndexPath) {
  let call = callManager.calls[indexPath.row]
  callManager.end(call: call)
}

When the user invokes swipe-to-delete on a row, the app will ask CallManager to end the corresponding call.

Build and run the project on your device, and perform the following steps:

1. Tap the plus button in the right-hand corner.
2. Enter any number, make sure “Incoming” is selected in the segmented control, and tap Done.
3. Within a few seconds, you’ll get an incoming call. Once you answer, you should see it listed as active on the UI.
4. Swipe left on the row representing the active call, and tap End.

At this point, your call will end. Neither the lock/home screens, nor the app will report any ongoing calls.

Hanging up now!

Other Provider Actions

If you look at the documentation page of CXProviderDelegate, you’ll notice that there are many more actions that the provider can perform, including muting, and grouping, or setting calls on hold. The latter sounds like a good feature for Hotline, so you’ll implement it now.

Whenever the user wants to set the held status of a call, the app will send an instance of CXSetHeldCallAction to the provider. It’s your job to implement the related delegate method. Open ProviderDelegate.swift, and add the following implementation to the class extension:

func provider(_ provider: CXProvider, perform action: CXSetHeldCallAction) {
  guard let call = callManager.callWithUUID(uuid: action.callUUID) else {
    action.fail()
    return
  }
  
  // 1.
  call.state = action.isOnHold ? .held : .active
  
  // 2.
  if call.state == .held {
    stopAudio()
  } else {
    startAudio()
  }
  
  // 3.
  action.fulfill()
}

This is fairly simple:

1. After getting the reference to the call, you’ll update its status according to the isOnHold property of the action.
2. Depending on the new status, you’ll want to start, or stop processing the call’s audio.
3. At this point, you can mark the action fulfilled.

Since this is also a user-initiated action, you’ll need to expand the CallManager class as well. Open CallManager.swift, and add the following implementation just below end(call:):

func setHeld(call: Call, onHold: Bool) {
  let setHeldCallAction = CXSetHeldCallAction(call: call.uuid, onHold: onHold)
  let transaction = CXTransaction()
  transaction.addAction(setHeldCallAction)
  
  requestTransaction(transaction)
}

The code is very similar to the end(call:) method, in fact, the only difference between the two is that this one will wrap an instance of CXSetHeldCallAction into the transaction. The action will contain the call’s UUID, and the held status.

Now it’s time to hook this action up to the UI. Open CallsViewController.swift, and find the class extension marked with UITableViewDelegate at the end of the file. Add the following implementation to the class extension, just below tableView(_:titleForDeleteConfirmationButtonForRowAt:):

override func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
  let call = callManager.calls[indexPath.row]
  call.state = call.state == .held ? .active : .held
  callManager?.setHeld(call: call, onHold: call.state == .held)
  
  tableView.reloadData()
}

Whenever the user taps a row, the code above will update the held status of the corresponding call.

Build and run the application, and start a new incoming call. If you tap the call’s cell, you’ll notice that the status label will change from “Active” to “On Hold”.

Handling Outgoing Calls

The final user-initiated action you’ll implement will be making outgoing calls. Open ProviderDelegate.swift and add the following implementation to the CXProviderDelegate class extension:

func provider(_ provider: CXProvider, perform action: CXStartCallAction) {
  let call = Call(uuid: action.callUUID, outgoing: true, handle: action.handle.value)
  // 1.
  configureAudioSession()
  // 2.
  call.connectedStateChanged = { [weak self, weak call] in
    guard let strongSelf = self, let call = call else { return }

    if call.connectedState == .pending {
      strongSelf.provider.reportOutgoingCall(with: call.uuid, startedConnectingAt: nil)
    } else if call.connectedState == .complete {
      strongSelf.provider.reportOutgoingCall(with: call.uuid, connectedAt: nil)
    }
  }
  // 3.
  call.start { [weak self, weak call] success in
    guard let strongSelf = self, let call = call else { return }

    if success {
      action.fulfill()
      strongSelf.callManager.add(call: call)
    } else {
      action.fail()
    }
  }
}

The provider will invoke this delegate method when an outgoing call request is made:

1. After creating a Call with the call’s UUID from the call manager, you’ll have to configure the app’s audio session. Just as with incoming calls, your responsibility at this point is only configuration. The actual processing will start later, when the provider(_:didActivate) delegate method is invoked.
2. The delegate will monitor the call’s lifecycle. It will initially report that the outgoing call has started connecting. When the call is finally connected, the provider delegate will report that as well.
3. Calling start() on the call will trigger its lifecycle changes. Upon a successful connection, the call can be marked as fulfilled.

Now that the provider delegate is ready to handle outgoing calls, it’s time to teach the app how to make one. :] Open CallManager.swift, and add the following method to the class:

func startCall(handle: String, videoEnabled: Bool) {
  // 1
  let handle = CXHandle(type: .phoneNumber, value: handle)
  // 2
  let startCallAction = CXStartCallAction(call: UUID(), handle: handle)
  // 3
  startCallAction.isVideo = videoEnabled
  let transaction = CXTransaction(action: startCallAction)
  
  requestTransaction(transaction)
}

This method will wrap a “Start call” action into a CXTransaction, and request it from the system.

1. A handle, represented by CXHandle can specify the handle type, and its value. Hotline supports phone number handles, so you’ll use it here as well.
2. A CXStartCallAction will receive a unique UUID, and a handle as input.
3. You can specify whether the call is audio-only, or a video call by setting the isVideo property of the action.

It’s time to hook up the new action to the UI. Open CallsViewController.swift, and replace the previous implementation of unwindForNewCall(_:) to match the following:

@IBAction private func unwindForNewCall(_ segue: UIStoryboardSegue) {
  let newCallController = segue.source as! NewCallViewController
  guard let handle = newCallController.handle else { return }
  let incoming = newCallController.incoming
  let videoEnabled = newCallController.videoEnabled
  
  if incoming {
    let backgroundTaskIdentifier = UIApplication.shared.beginBackgroundTask(expirationHandler: nil)
    DispatchQueue.main.asyncAfter(wallDeadline: DispatchWallTime.now() + 1.5) {
      AppDelegate.shared.displayIncomingCall(uuid: UUID(), handle: handle, hasVideo: videoEnabled) { _ in
        UIApplication.shared.endBackgroundTask(backgroundTaskIdentifier)
      }
    }
  } else {
    callManager.startCall(handle: handle, videoEnabled: videoEnabled)
  }
}

There’s one subtle change in the code: whenever incoming is false, the view controller will ask the call manager to start an outgoing call.

That’s all you’ll need to make calls. It’s time to start testing! Build and run the app on your device. Tap the plus button in the right-hand corner to start a new call, but this time make sure that you select “Outgoing” from the segmented control.

At this point you should see the new call appear in your list. You’ll also see different status labels based on the current stage of the call:

I can make calls now?!

Managing Multiple Calls

It’s easy to imagine a scenario where a Hotline user would receive multiple calls. You can simulate this by first placing an outgoing call, then an incoming call and pressing the Home button before the incoming call comes in. At this point, the app presents the user with the following screen:

The system will let the user decide how to resolve the issue. Based on the choice, it will wrap up multiple actions into a CXTransaction. For example if the user chooses to end the ongoing call, and answer the new one, the system will create a CXEndCallAction for the former and a CXStartCallAction for the latter. Both actions will be wrapped into a transaction and sent to the provider, which will process them individually. So if your app already knows how to fulfill the individual requests, there’s no further action required!

Implementing features without additional code!

You can test it by resolving the scenario above; the list of calls will reflect your choice. The app will only process one audio session at a time. If you choose to resume a call, the other will be put on hold automatically.

Creating a Call Directory Extension

The directory extension is a new extension point offered by CallKit. It allows your VoIP app to:

• Add phone numbers to the system’s block list.
• Identify incoming calls by their phone number or other uniquely identifying information, such as email address.

Whenever the system receives a call, it will check the address book for a match; if it doesn’t find one, it can also check in app-specific directory extensions. Why not add a directory extension to Hotline?

Back in Xcode, go to File\New\Target… and choose Call Directory Extension. Name it HotlineDirectory, and click Finish. Xcode will automatically create a new file, CallDirectoryHandler.swift. Locate it in the project navigator, and check what’s inside.

The first method you’ll find is beginRequest(with:). This method will be invoked when your extension is initialized. In case of any errors, the extension will tell the host app to cancel the extension request by invoking cancelRequest(withError:). It relies on two other methods to build the app-specific directory.

addBlockingPhoneNumber(to:) will collect all the phone numbers, which should be blocked. Replace its implementation with the following:

private func addBlockingPhoneNumbers(to context: CXCallDirectoryExtensionContext) throws {
  let phoneNumbers: [CXCallDirectoryPhoneNumber] = [ 1234 ]
  for phoneNumber in phoneNumbers {
    context.addBlockingEntry(withNextSequentialPhoneNumber: phoneNumber)
  }
}

Invoking addBlockingEntry(withNextSequentialPhoneNumber:) with a given phone number will add it to the block list. When a number is blocked, the system telephony provider will not display any calls from that number.

Now take a look at addIdentificationPhoneNumbers(to:). Replace the method body with the code below:

private func addIdentificationPhoneNumbers(to context: CXCallDirectoryExtensionContext) throws {
  let phoneNumbers: [CXCallDirectoryPhoneNumber] = [ 1111 ]
  let labels = [ "RW Tutorial Team" ]
  
  for (phoneNumber, label) in zip(phoneNumbers, labels) {
    context.addIdentificationEntry(withNextSequentialPhoneNumber: phoneNumber, label: label)
  }
}

Invoking addIdentificationEntry(withNextSequentialPhoneNumber:label:) with a specified phone number and label will create a new identification entry. Whenever the system receives a call from this number, the call UI will display the matching label to the user.

It’s time to test your new extension. Build and run the Hotline scheme on your device. At this point your extension may not yet be active. To enable it, do the following steps:

1. Go to the Settings app
2. Select Phone
3. Select Call Blocking & Identification
4. Enable Hotline

Testing a blocked call is easy: just launch Hotline, and simulate an incoming call from the number 1234. You’ll notice that the system doesn’t report anything. In fact, if you put a breakpoint in the implementation of reportIncomingCall(uuid:handle:hasVideo:completion:) in ProviderDelegate, you’ll notice that reportNewIncomingCall(withupdate:completion:) will even report an error.

To test identifying calls, launch Hotline again, and simulate a new call; but this time, enter the number 1111. You’ll be presented with the following call UI:

FYI: that’s not a real number :]

This app is awesome!

Congratulations! You’ve created an app which leverages CallKit to provide a first-party VoIP experience! :]

Where to Go From Here?

You can download the completed project for this tutorial here.

If you wish to learn more about CallKit, check out Session 230 from WWDC 2016.

I hope you enjoyed this CallKit tutorial. If you have any questions or comments, please join the forum discussion below!