iOS Quickstart: Making Outgoing Calls

The Xcode Project

Please open HelloMonkey.xcodeproj Xcode project in Quickstart folder. This project is based on "View-based Application" template for iPhone that has already been configured to work with Twilio Client library. Please see the Twilio Client iOS SDK Overview for details on modifying an Xcode project to use Twilio Client.

The HelloMonkey app is very simple, presenting "Dial" and "Hangup" buttons, and a text field for who the app should call. The user interface elements have already been wired up to the HelloMonkeyViewController class in Interface Builder.

In this step, you'll fill in the code to give the app its behavior, learning how to use the Twilio Client iOS SDK in the process.

Creating a Device

The primary class for connecting to Twilio services from your app is TCDevice. This class represents a soft "device" that knows how to speak to Twilio services, coordinates service authorization with Twilio, listens for incoming connections, and establishes outgoing connections. An instance of this class is created using a "capability token", described in the next section.

You'll use a TCDevice to initiate outgoing calls and listen for incoming calls. Let's create an instance and wire it up!

Add a member variable of type TCDevice to HelloMonkeyViewController.m like so:

#import "HelloMonkeyViewController.h"
#import "TwilioClient.h"

@interface HelloMonkeyViewController()
    TCDevice* _phone;
    TCConnection* _connection;

To initialize a device, you'll change the URL to point to your server's /token URL and pass the resulting string to -initWithCapabilityToken:delegate:.

Make sure you swap in your back-end server's `/token` URL for the sample URL in `HelloMonkeyViewController`'s `viewDidLoad` method.
- (void)viewDidLoad
    NSURL *url = [NSURL URLWithString:@""];
    NSError *error = nil;
    NSString *token = [NSString stringWithContentsOfURL:url encoding:NSUTF8StringEncoding error:&error];
    if (token == nil) {
        NSLog(@"Error retrieving token: %@", [error localizedDescription]);
    } else {
        _phone = [[TCDevice alloc] initWithCapabilityToken:token delegate:nil];

Making an HTTP request to the /token endpoint returns a capability token--a string that, when given to a TCDevice in your iOS app, grants it capabilities such as making outgoing calls or allowing incoming calls.

Capability tokens are an important part of Twilio Client, so let's take a moment to explain them. You use capability tokens to sign communications from your iOS app to Twilio. In a production application, these tokens are created by you on your server and allow you to specify what capabilities are going to be available to your app, such as whether it can receive incoming connections, make outgoing connections, etc.

For the security of your Twilio account, you should not embed a Capability Token or your Twilio Account's Auth Token in the app you submit to the App Store.

You can read more about capability tokens and their best practices here.

Tokens always have an expiration, which means all tokens have a limited lifetime to protect you from abuse. The token generated here is valid for one hour unless otherwise specified. To specify a different period of time, pass in the number of seconds as the expires parameter to TwilioCapability.generate() -- for example, for a token that expires after 5 minutes, call TwilioCapability.generate(expires = 300). The maximum allowed lifetime for a token is 24 hours.

Now, back to coding! If you compile and run this code, you should see the following:

iOS app with Dial and Hangup buttons

Now, we've got an app that can create outgoing connections and receive incoming connections.

For the time being, we'll focus on making an outgoing connection. The connection will call a Twilio sample application that responds with a friendly greeting.

Dialing Out

Let's add a method to HelloMonkeyViewController to initiate a connection. To make a connection, we call the TCDevice's -connect:(NSDictionary*)params delegate:(id<TCConnectionDelegate>)delegate method. Just pass in nil parameters and a nil delegate for the moment; we'll do more with these arguments later.

- (IBAction)dialButtonPressed:(id)sender
    _connection = [_phone connect:nil delegate:nil];

Connections to Twilio, either incoming or outgoing, are represented by instances of the class TCConnection. In addition, status callbacks are provided to objects that implement the delegate protocols TCDeviceDelegate and TCConnectionDelegate.

If you now compile the app and run it, you should be able to click the "Dial" button and hear the greeting. Awesome!

Wouldn't it be nice if you could also hang up on a connection if you don't want to hear the whole thing? Let's go do that now.

Next: Hanging up from your iOS Device »