Discussion

The default logging level is TVOLogLevelError. TwilioVoice and its components use NSLog internally.

Discussion

Sending stats data to Insights is enabled by default.

Discussion

The default region uses Global Low Latency routing, which establishes a connection with the closest region to the user. If you are specifying a region via the TwilioVoice.region property you must do so before [TwilioVoice connectWithAccessToken:delegate:] or [TwilioVoice handleNotification:delegate:delegateQueue:] is called.

Discussion

If you wish to provide your own TVOAudioDevice then you must set it before performing any other actions with the SDK like connecting to a Call. It is also possible to change the device when you are no longer connected to any Calls and have destroyed all other SDK objects.

Discussion

Registering for push notifications is required to receive incoming call notification messages through Twilio’s infrastructure. Once successfully registered, the registered binding has a time-to-live(TTL) of 1 year. If the registered binding is inactive for 1 year it is deleted and push notifications to the registered identity will not succeed. However, whenever the registered binding is used to reach the registered identity the TTL is reset to 1 year. A successful registration will ensure that push notifications will arrive via the APNs for the lifetime of the registration device token provided by the APNs instance.

The identity provided in the Access Token may only contain alpha-numeric and underscore characters. Other characters, including spaces, will result in undefined behavior.

If the registration is successful the completion handler will contain a Null NSError. If the registration fails, the completion handler will have a nonnull NSError with UserInfo string describing the reason for failure.

Insights

An example of using the registration API

[TwilioVoice registerWithAccessToken:accessToken
    deviceToken:deviceToken
    completion:^(NSError *error) {
        if(error != nil) {
            NSLog("Failed to register for incoming push: %@\n\t  - reason: %@", [error localizedDescription], [error localizedFailureReason]);
        } else {
            NSLog("Registration successful");
        }
}];

Discussion

Call this method when you no longer want to receive push notifications for incoming Calls.

The identity provided in the Access Token may only contain alpha-numeric and underscore characters. Other characters, including spaces, will result in undefined behavior.

If the unregistration is successful the completion handler will contain a Null NSError. If the unregistration fails, the completion handler will have a nonnull NSError with UserInfo string describing the reason for failure.

Insights

An example of using the unregistration API

[TwilioVoice unregisterWithAccessToken:accessToken
    deviceToken:deviceToken
    completion:^(NSError *error) {
        if(error != nil) {
            NSLog("Failed to unregister for incoming push: %@\n\t  - reason: %@", [error localizedDescription], [error localizedFailureReason]);
        } else {
            NSLog("Unregistration successful");
        }
}];

Discussion

This method will synchronously process call notification payload and call the provided delegate on the same dispatch queue.

If you are specifying a region via the TwilioVoice.region property you must do so before calling this method.

Twilio sends a call notification via Apple VoIP Service. The notification type is encoded in the dictionary with the key twi_message_type and the value twilio.voice.call.

A call notification is sent when someone wants to reach the registered identity. Passing a call notification into this method will result in a callInviteReceived: callback with a TVOCallInvite object and return YES.

To ensure that a cancellation is reported via the [TVONotificationDelegate cancelledCallInviteReceived:error:] callback, the TVOCallInvite must be retained until the call is accepted or rejected.

Insights

An example of using the handleNotification API

@interface CallViewController () <PKPushRegistryDelegate, TVONotificationDelegate, TVOCallDelegate, ... >

// property declarations

@end

@implementation CallViewController

// ViewController setup and other code ...

#pragma mark - PKPushRegistryDelegate

- (void)pushRegistry:(PKPushRegistry *)registry
    didReceiveIncomingPushWithPayload:(PKPushPayload *)payload
    forType:(NSString *)type {
        NSLog(@"Received incoming push: %@", payload.dictionaryPayload);

        if ([type isEqualToString:PKPushTypeVoIP]) {
            if (![TwilioVoice handleNotification:payload.dictionaryPayload delegate:self]) {
                NSLog(@"The push notification was not a Twilio Voice push notification");
        }
    }
}

#pragma mark - TVONotificationDelegate methods

- (void)callInviteReceived:(TVOCallInvite *)callInvite {
    // handle call invite
}

- (void)cancelledCallInviteReceived:(TVOCancelledCallInvite *)cancelledCallInvite {
    // handle cancelled call invite
}

@end

Discussion

This method is guaranteed to return a TVOCall object. It’s possible for the returned Call to either succeed or fail to connect.

The identity provided in the Access Token may only contain alpha-numeric and underscore characters. Other characters, including spaces, will result in undefined behavior.

If you are specifying a region via the TwilioVoice.region property you must do so before calling this method.

The TVOCallDelegate will receive the Call state update callbacks. The callbacks are listed here.

If connect fails, call:didFailToConnectWithError or call:didDisconnectWithError callback is raised with an NSError object. [error localizedDescription], [error localizedFailureReason] and [error code] provide details of the failure.

If any authentication error occurs then the SDK will receive one of the following errors.

If any connection fails because of any other error then the SDK will receive one of the following errors.

Insights

If connection fails then an error event will be published.

An example of using the connectWithAccessToken:delegate: API

@interface CallViewController () <TVOCallDelegate, ... >

// property declarations

@end

@implementation CallViewController

// ViewController setup and other code ...

- (void)makeCall:(NSString*)accessToken
    self.call = [TwilioVoice connectWithAccessToken:accessToken delegate:self];
}

#pragma mark - TVOCallDelegate

- (void)callDidStartRinging:(TVOCall *)call {
    NSLog(@"Call is ringing at called party %@", call.to);
}

- (void)call:(TVOCall *)call didFailToConnectWithError:(NSError *)error {
    NSLog("Failed to Connect the Call: %@\n\t  - reason: %@", [error localizedDescription], [error localizedFailureReason]);
}

- (void)call:(TVOCall *)call didDisconnectWithError:(NSError *)error {
    if (error) {
        NSLog(@"Call disconnected with error: %@", error);
    } else {
        NSLog(@"Call disconnected");
    }
}

- (void)callDidConnect:(TVOCall *)call {
    NSLog(@"Call connected.");
}

@end

Discussion

This method is guaranteed to return a TVOCall object. It’s possible for the returned Call to either succeed or fail to connect. Use the TVOConnectOptions builder to specify Call parameters and UUID.

If you are specifying a region via the TwilioVoice.region property you must do so before calling this method.

The TVOCallDelegate will receive the Call state update callbacks. The callbacks are same as connectWithAccessToken:delegate: API.

If connect fails, call:didFailToConnectWithError or call:didDisconnectWithError callback is raised with an NSError object. [error localizedDescription], [error localizedFailureReason] and [error code] provide details of the failure. The error codes are same as connectWithAccessToken:delegate: API.

Insights

If connection fails then an error event will be published.

An example of using the connectWithAccessToken:delegate API

@interface CallViewController () <TVOCallDelegate, ... >

// property declarations

@end

@implementation CallViewController

// ViewController setup and other code ...

- (void)makeCall:(NSString *)accessToken uuid:(NSString *)uuid region:(NSString *)region to:(NSString *)phoneNumber
    NSMutableDictionary *params = [NSMutableDictionary dictionary];

    if ([to length] > 0) {
        params[@"Mode"] = @"Voice";
        params[@"PhoneNumber"] = phoneNumber;
    }

    TVOConnectOptions *connectOptions = [TVOConnectOptions optionsWithAccessToken:accessToken
        block:^(TVOConnectOptionsBuilder *builder) {
            builder.params = params;
            builder.uuid = uuid;
    }];

    self.call = [TwilioVoice connectWithOptions:connectOptions delegate:self];
}

#pragma mark - TVOCallDelegate

- (void)callDidStartRinging:(TVOCall *)call {
    NSLog(@"Call is ringing at called party %@", call.to);
}

- (void)call:(TVOCall *)call didFailToConnectWithError:(NSError *)error {
    NSLog("Failed to Connect the Call: %@\n\t  - reason: %@", [error localizedDescription], [error localizedFailureReason]);
}

- (void)call:(TVOCall *)call didDisconnectWithError:(NSError *)error {
    if (error) {
        NSLog(@"Call disconnected with error: %@", error);
    } else {
        NSLog(@"Call disconnected");
    }
}

- (void)callDidConnect:(TVOCall *)call {
    NSLog(@"Call connected.");
}

@end