Twilio Voice Swift Quickstart for iOS

Get started with Voice on iOS:

Quickstart - Run the quickstart app
Access Tokens - Using access tokens
Managing Audio Interruptions - Managing audio interruptions
More Documentation - More documentation related to the Voice iOS SDK
Issues and Support - Filing issues and general support

Quickstart

To get started with the quickstart application follow these steps. Steps 1-6 will enable the application to make a call. The remaining steps 7-10 will enable the application to receive incoming calls in the form of push notifications using Apple’s VoIP Service.

Install the TwilioVoice framework
Create a Voice API key
Configure a server to generate an access token to be used in the app
Create a TwiML application
Configure your application server
Run the app
Create a VoIP Service Certificate
Create a Push Credential with your VoIP Service Certificate
Configure Xcode project settings for VoIP push notifications
Receive an incoming call
Make client to client call
Make client to PSTN call

1. Install the TwilioVoice framework

Carthage

Add the following line to your Cartfile

github "twilio/twilio-voice-ios"

Then run carthage bootstrap (or carthage update if you are updating your SDKs)

On your application targets’ “Build Phases” settings tab, click the “+” icon and choose “New Run Script Phase”. Create a Run Script in which you specify your shell (ex: /bin/sh), add the following contents to the script area below the shell:

/usr/local/bin/carthage copy-frameworks

Add the paths to the frameworks you want to use under “Input Files”, e.g.:

$(SRCROOT)/Carthage/Build/iOS/TwilioVoice.framework

Cocoapods

Under the quickstart path, run pod install and let the Cocoapods library create the workspace for you. Also please make sure to use Cocoapods v1.0 and later. Once Cocoapods finishes installing, open the SwiftVoiceQuickstart.xcworkspace and you will find a basic Swift quickstart project and a CallKit quickstart project.

Note: You may need to update the CocoaPods Master Spec Repo by running pod repo update master in order to fetch the latest specs for TwilioVoice.

2. Create a Voice API key

Go to the Voice API Keys page and create a new API key:

Save the generated API_KEY and API_KEY_SECRET in your notepad. You will need them in the next step.

3. Configure a server to generate an access token to be used in the app

Download one of the starter projects for the server.

Follow the instructions in the server's README to get the application server up and running locally and accessible via the public Internet. For now just replace the Twilio Account SID that you can obtain from the console, and the API_KEY and API_SECRET you obtained in the previous step.

ACCOUNT_SID = 'AC***'
API_KEY = 'SK***'
API_KEY_SECRET = '***'

4. Create a TwiML application

Next, we need to create a TwiML application. A TwiML application identifies a public URL for retrieving TwiML call control instructions. When your iOS app makes a call to the Twilio cloud, Twilio will make a webhook request to this URL, your application server will respond with generated TwiML, and Twilio will execute the instructions you’ve provided. To create a TwiML application, go to the TwiML app page. Create a new TwiML application, and use the public URL of your application server’s /makeCall endpoint as the Voice Request URL (If your app server is written in PHP, then you need .php extension at the end).

As you can see we’ve used our ngrok public address in the Request URL field above. Save your TwiML Application configuration, and grab the TwiML Application SID (a long identifier beginning with the characters AP).

5. Configure your application server

Let's put the remaining APP_SID configuration info into your server code.

ACCOUNT_SID = 'AC***'
API_KEY = 'SK***'
API_KEY_SECRET = '***'
APP_SID = 'AP***'

Once you’ve done that, restart the server so it uses the new configuration info. Now it's time to test.

Open up a browser and visit the URL for your application server's Access Token endpoint: https://{YOUR_SERVER_URL}/accessToken (If your app server is written in PHP, then you need .php extension at the end). If everything is configured correctly, you should see a long string of letters and numbers, which is a Twilio Access Token. Your iOS app will use a token like this to connect to Twilio.

6. Run the app

Now let’s go back to the SwiftVoiceQuickstart.xcworkspace. Update the placeholder of baseURLString with your ngrok public URL

import UIKit
import AVFoundation
import PushKit
import TwilioVoice

let baseURLString = "https://3b57e324.ngrok.io"
let accessTokenEndpoint = "/accessToken"
let identity = "alice"
let twimlParamTo = "to"

class ViewController: UIViewController, PKPushRegistryDelegate, TVONotificationDelegate, TVOCallDelegate, AVAudioPlayerDelegate, UITextFieldDelegate {

Build and run the app

Leave the text field empty and press the call button to start a call. You will hear the congratulatory message. Support for dialing another client or number is described in steps 11 and 12. Tap "Hang Up" to disconnect.

7. Create VoIP Service Certificate

The Programmable Voice SDK uses Apple’s VoIP Services to let your application know when it is receiving an incoming call. If you want your users to receive incoming calls, you’ll need to enable VoIP Services in your application and generate a VoIP Services Certificate.

Go to Apple Developer portal and you’ll need to do the following:

An Apple Developer membership to be able to create the certificate.
Make sure your App ID has the “Push Notifications” service enabled.
Create a corresponding Provisioning Profile for your app ID.
Create an Apple VoIP Services Certificate for this app.

8. Create a Push Credential with your VoIP Service Certificate

Once you have generated the VoIP Services Certificate, you will need to upload it to Twilio so that Twilio can send push notifications to your app on your behalf.

Export your VoIP Service Certificate as a .p12 file, then extract the certificate and private key from the .p12 file using the openssl command

$> openssl pkcs12 -in PATH_TO_YOUR_P12 -nocerts -out key.pem
$> openssl rsa -in key.pem -out key.pem
$> openssl pkcs12 -in PATH_TO_YOUR_P12 -clcerts -nokeys -out cert.pem

Go to the Push Credentials page and create a new Push Credential. Paste the certificate and private key extracted from your certificate. You must paste the keys in as plaintext:

For the cert.pem you should paste everything from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.
For the key.pem you should paste everything from -----BEGIN RSA PRIVATE KEY----- to -----END RSA PRIVATE KEY-----.

Remember to check the “Sandbox” option. This is important. The VoIP Service Certificate you generated can be used both in production and with Apple's sandbox infrastructure. Checking this box tells Twilio to send your pushes to the Apple sandbox infrastructure which is appropriate with your development provisioning profile.

Once the app is ready for store submission, update the plist with “APS Environment: production” and create another Push Credential with the same VoIP Certificate but without checking the sandbox option.

Now let's go back to your server code and update the Push Credential SID. The Push Credential SID will now be embedded in your access token.

PUSH_CREDENTIAL_SID = 'CR***'

9. Configure Xcode project settings for push notifications

On the project’s Capabilities tab, enable “Push Notifications”. In Xcode 8 or earlier, enable both “Voice over IP” and “Audio, AirPlay and Picture in Picture” capabilities in the Background Modes

In Xcode 9+, add a "UIBackgroundModes" dictionary with "audio" and "voip" to the app's plist.

<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
  <string>voip</string>
</array>

10. Receive an incoming call

You are now ready to receive incoming calls. Rebuild your app and hit your application server's /placeCall endpoint: https://{YOUR_SERVER_URL}/placeCall (If your app server is written in PHP, then you need .php extension at the end). This will trigger a Twilio REST API request that will make an inbound call to your mobile app. Once your app accepts the call, you should hear a congratulatory message.

11. Make client to client call

To make client to client calls, you need the application running on two devices. To run the application on an additional device, make sure you use a different identity in your access token when registering the new device. For example, change kIdentity to bob and run the application

let accessTokenEndpoint = "/accessToken"
let identity = "bob"
let twimlParamTo = "to"

Use the text field to specify the identity of the call receiver, then tap the “Call” button to make a call. The TwiML parameters used in TwilioVoice.call() method should match the name used in the server.

12. Make client to PSTN call

A verified phone number is one that you can use as your Caller ID when making outbound calls with Twilio. This number has not been ported into Twilio and you do not pay Twilio for this phone number.

To make client to number calls, first get a valid Twilio number to your account via https://www.twilio.com/console/phone-numbers/verified. Update your server code and replace CALLER_NUMBER with the verified number. Restart the server so it uses the new value. Voice Request URL of your TwiML application should point to the public URL of your application server’s /makeCall endpoint.

Access Tokens

The access token generated by your server component is a jwt that contains a grant for Programmable Voice, an identity that you specify, and a time-to-live that sets the lifetime of the generated access token. The default time-to-live is 1 hour and is configurable up to 24 hours using the Twilio helper libraries.

Uses

In the iOS SDK the access token is used for the following:

To make an outgoing call via TwilioVoice.call(...)
To register or unregister for incoming notifications using VoIP Push Notifications via TwilioVoice.registerWithAccessToken(...) and TwilioVoice.unregisterWithAccessToken(...). Once registered, incoming notifications are handled via a TVOCallInvite where you can choose to accept or reject the invite. When accepting the call an access token is not required. Internally the TVOCallInvite has its own access token that ensures it can connect to our infrastructure.

Managing Expiry

As mentioned above, an access token will eventually expire. If an access token has expired, our infrastructure will return error TVOErrorAccessTokenExpired/20104 via TVOCallDelegate or a completion error when registering.

There are number of techniques you can use to ensure that access token expiry is managed accordingly:

Always fetch a new access token from your access token server before making an outbound call.
Retain the access token until getting a TVOErrorAccessTokenExpired/20104 error before fetching a new access token.
Retain the access token along with the timestamp of when it was requested so you can verify ahead of time whether the token has already expired based on the time-to-live being used by your server.
Prefetch the access token whenever the UIApplication, or UIViewController associated with an outgoing call is created.

Managing Audio Interruptions

Different versions of iOS deal with AVAudioSession interruptions sightly differently. This section documents how the Programmable Voice iOS SDK manages audio interruptions and resumes call audio after the interruption ends. There are currently some cases that the SDK cannot resume call audio automatically because iOS does not provide the necessary notifications to indicate that the interruption has ended.

How Programmable Voice iOS SDK handles audio interruption

The SDK registers itself as an observer of AVAudioSessionInterruptionNotification in TwilioVoice.initialize().
When the notification is fired and the interruption type is AVAudioSessionInterruptionTypeBegan, the SDK automatically disables the audio device and puts any active Calls on hold.
When the SDK receives the notification with AVAudioSessionInterruptionTypeEnded, it re-enables the audio device and resumes the audio of active Calls.
- We have noticed that on iOS 8 and 9, the interruption notification with AVAudioSessionInterruptionTypeEnded is not always fired therefore the SDK is not able to resume call audio automatically. This is a known issue and an alternative way is to use the UIApplicationDidBecomeActiveNotification and resume audio when the app is active again after the interruption.

Notifications in different iOS versions

Below is a table listing the system notifications received with different steps to trigger audio interruptions and resume during an active Voice SDK call. (Assume the app is in an active Voice SDK call)

Scenario	Notification of interruption-begins	Notification of interruption-ends	Call audio resumes?	Note
PSTN Interruption
A. PSTN interruption Accept the PSTN incoming call Remote party of PSTN call hangs up	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	✅ iOS 9 ✅ iOS 10 ✅ iOS 11
B. PSTN interruption Accept the PSTN incoming call Local party of PSTN call hangs up	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	✅ iOS 9 ✅ iOS 10 ✅ iOS 11
C. PSTN interruption Reject PSTN	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	✅ iOS 9 ✅ iOS 10 ✅ iOS 11
D. PSTN interruption Ignore PSTN	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	✅ iOS 9 ✅ iOS 10 ✅ iOS 11
E. PSTN interruption Remote party of PSTN call hangs up before local party can answer	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	✅ iOS 9 ✅ iOS 10 ✅ iOS 11
Other Types of Audio Interruption (YouTube app as example)
F. Switch to YouTube app and play video Stop the video Switch back to Voice app	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	❌ iOS 9 ✅ iOS 10 ✅ iOS 11	❌ iOS 9 ✅ iOS 10 ✅ iOS 11	Interruption-ended notification is not fired on iOS 9. Interruption-ended notification is not fired until few seconds after switching back to the Voice app on iOS 10/11. The `AVAudioSessionInterruptionOptionShouldResume` flag is `false`.
G. Switch to YouTube app and play video Switch back to Voice app without stopping the video	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	❌ iOS 9 ✅ iOS 10 ✅ iOS 11	❌ iOS 9 ✅ iOS 10 ✅ iOS 11	Interruption-ended notification is not fired on iOS 9. Interruption-ended notification is not fired until few seconds after switching back to the Voice app on iOS 10/11. The `AVAudioSessionInterruptionOptionShouldResume` flag is `false`.
H. Switch to YouTube app and play video Double-press Home button and terminate YouTube app Back to Voice app	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	✅ iOS 9 ✅ iOS 10 ✅ iOS 11	Interruption-ended notification is not fired until the Voice app is back to the active state. The `AVAudioSessionInterruptionOptionShouldResume` flag is `false`.

CallKit

On iOS 10 and later, CallKit (if integrated) takes care of the interruption by providing a set of delegate methods so that the application can respond with proper audio device handling and state transitioning in order to ensure call audio works after the interruption has ended.

Notifications & Callbacks during Interruption

By enabling the supportsHolding flag of the CXCallUpdate object when reporting a call to the CallKit framework, you will see the “Hold & Accept” option when there is another PSTN or CallKit-enabled call. By pressing the “Hold & Accept” option, a series of things and callbacks will happen:

The provider:performSetHeldCallAction: delegate method is called with CXSetHeldCallAction.isOnHold = YES. Put the Voice call on-hold here and fulfill the action.
The AVAudioSessionInterruptionNotification notification is fired to indicate the AVAudioSession interruption has started.
CallKit will deactivate the AVAudioSession of your app and fire the provider:didDeactivateAudioSession: callback. You need to disable the SDK audio device by calling TwilioVoice.audioEnabled = NO.
When the interrupting call ends, instead of getting the AVAudioSessionInterruptionNotification notification, the system will notify that you can resume the call audio that was put on-hold when the interruption began by calling the provider:performSetHeldCallAction: method again. Note that this callback is not fired if the interrupting call is disconnected by the remote party.
The AVAudioSession of the app will be activated again and you should re-enable the audio device of the SDK TwilioVoice.audioEnabled = YES in the provider:didActivateAudioSession: method.

Scenario	Audio resumes after interrupion?	Note
A. Hold & Accept Hang up PSTN interruption on the local end	✅ iOS 10 ✅ iOS 11
B. Hold & Accept Remote party hangs up PSTN interruption	❌ iOS 10 ❌ iOS 11	`provider:performSetHeldCallAction:` not called after the interruption ends.
C. Hold & Accept Switch back to the Voice Call on system UI	✅ iOS 10 ✅ iOS 11
D. Reject	✅ iOS 10 ✅ iOS 11	No actual audio interruption happened since the interrupting call is not answered
E. Ignore	✅ iOS 10 ✅ iOS 11	No actual audio interruption happened since the interrupting call is not answered

In case 2, CallKit does not automatically resume call audio by calling provider:performSetHeldCallAction: method, but the system UI will show that the Voice call is still on-hold. You can resume the call using the "Hold" button, or use the CXSetHeldCallAction to lift the on-hold state programmatically. The app is also responsible of updating UI state to indicate the "hold" state of the call to avoid user confusion.

// Resume call audio programmatically after interruption
CXSetHeldCallAction *setHeldCallAction = [[CXSetHeldCallAction alloc] initWithCallUUID:self.call.uuid onHold:holdSwitch.on];
CXTransaction *transaction = [[CXTransaction alloc] initWithAction:setHeldCallAction];
[self.callKitCallController requestTransaction:transaction completion:^(NSError *error) {
    if (error) {
        NSLog(@"Failed to submit set-call-held transaction request");
    } else {
        NSLog(@"Set-call-held transaction successfully done");
    }
}];

Twilio Helper Libraries

To learn more about how to use TwiML and the Programmable Voice Calls API, check out our TwiML quickstarts:

Issues and Support

Please file any issues you find here on Github: Voice Swift Quickstart.

For general inquiries related to the Voice SDK you can file a support ticket.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 84 Commits
.github		.github
Images		Images
Ringtones		Ringtones
SwiftVoiceCallKitQuickstart.xcodeproj		SwiftVoiceCallKitQuickstart.xcodeproj
SwiftVoiceCallKitQuickstart		SwiftVoiceCallKitQuickstart
SwiftVoiceQuickstart.xcodeproj		SwiftVoiceQuickstart.xcodeproj
SwiftVoiceQuickstart		SwiftVoiceQuickstart
.gitignore		.gitignore
LICENSE		LICENSE
Podfile		Podfile
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Twilio Voice Swift Quickstart for iOS

Get started with Voice on iOS:

Quickstart

1. Install the TwilioVoice framework

2. Create a Voice API key

3. Configure a server to generate an access token to be used in the app

4. Create a TwiML application

5. Configure your application server

6. Run the app

7. Create VoIP Service Certificate

8. Create a Push Credential with your VoIP Service Certificate

9. Configure Xcode project settings for push notifications

10. Receive an incoming call

11. Make client to client call

12. Make client to PSTN call

Access Tokens

Uses

Managing Expiry

Managing Audio Interruptions

How Programmable Voice iOS SDK handles audio interruption

Notifications in different iOS versions

CallKit

Notifications & Callbacks during Interruption

More Documentation

Twilio Helper Libraries

Issues and Support

License

About

Releases

Packages

Languages

License

iSenseLabs/voice-quickstart-swift

Folders and files

Latest commit

History

Repository files navigation

Twilio Voice Swift Quickstart for iOS

Get started with Voice on iOS:

Quickstart

1. Install the TwilioVoice framework

2. Create a Voice API key

3. Configure a server to generate an access token to be used in the app

4. Create a TwiML application

5. Configure your application server

6. Run the app

7. Create VoIP Service Certificate

8. Create a Push Credential with your VoIP Service Certificate

9. Configure Xcode project settings for push notifications

10. Receive an incoming call

11. Make client to client call

12. Make client to PSTN call

Access Tokens

Uses

Managing Expiry

Managing Audio Interruptions

How Programmable Voice iOS SDK handles audio interruption

Notifications in different iOS versions

CallKit

Notifications & Callbacks during Interruption

More Documentation

Twilio Helper Libraries

Issues and Support

License

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages