TVOCallInvite Class Reference

Inherits from NSObject
Declared in TVOCallInvite.h

Overview

The TVOCallInvite object represents an incoming Call Invite. TVOCallInvites are not created directly; they are returned by the [TVONotificationDelegate callInviteReceived:] delegate method.

CallKit specific additions.

Properties

  from

From value of the Call Invite.

@property (nonatomic, copy, readonly, nullable) NSString *from

Discussion

This may be nil if the notification passed in [TwilioVoice handleNotification:delegate:] method does not have valid information in it.

Declared In

TVOCallInvite.h

  to

To value of the Call Invite.

@property (nonatomic, copy, readonly, nonnull) NSString *to

Declared In

TVOCallInvite.h

  callSid

A server assigned identifier (SID) for the incoming Call.

@property (nonatomic, copy, readonly, nonnull) NSString *callSid

Discussion

Accepting a TVOCallInvite yields a TVOCall which inherits this SID.

See Also

Declared In

TVOCallInvite.h

  customParameters

Custom parameters embedded in the VoIP notification payload.

@property (nonatomic, strong, readonly, nullable) NSDictionary<NSString*NSString*> *customParameters

Discussion

The custom parameters will be received in the notification payload with the twi_params key and in query-string format, e.g. key1=value1&key2=value2. To receive custom parameters on the mobile client, add <Parameter> tags into the <Client> tag in the TwiML response.

<?xml version=“1.0” encoding=“UTF-8”?> bob

The customParameters value would be:

{ “caller_first_name” = “alice”; “caller_last_name” = “smith”; }

Note: While the value field passed into <Parameter> gets URI encoded by the Twilio infrastructure and URI decoded when parsed during the creation of a TVOCallInvite, the name does not get URI encoded or decoded. As a result, it is recommended that the name field only use ASCII characters.

Declared In

TVOCallInvite.h

Call Invite Actions

– acceptWithDelegate:

Accepts the incoming Call Invite.

- (nonnull TVOCall *)acceptWithDelegate:(nonnull id<TVOCallDelegate>)delegate

Parameters

delegate

A TVOCallDelegate to receive Call state updates.

Return Value

A TVOCall object.

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 TVOCallDelegate will receive the Call state update callbacks. The callbacks are listed here.

Callback NameDescriptionSince version
call:didFailToConnectWithError The call failed to connect. An NSError object provides details of the root cause.3.0.0-preview1
callDidStartRinging: This callback should not be invoked when calling [TVOCallInvite acceptWithDelegate:].3.0.0-preview2
callDidConnect: The Call has connected.3.0.0-preview1
call:didDisconnectWithError The Call was disconnected. If the Call ends due to an error the NSError is non-null. If the call ends normally NSError is nil.3.0.0-preview1

If accept 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 [TVOCallInvite acceptWithDelegate:] fails due to an authentication error, the SDK receives the following error.

Authentication ErrorsError CodeDescription
TVOErrorAuthFailureCodeError20151Twilio failed to authenticate the client

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

Connection ErrorsError CodeDescription
TVOErrorConnectionError31005Connection error
TVOErrorCallCancelledError31008Call Cancelled
TVOErrorAuthorizationError31201Authorization error
TVOErrorSignalingConnectionDisconnectedError53001Signaling connection disconnected
TVOErrorMediaClientLocalDescFailedError53400Client is unable to create or apply a local media description
TVOErrorMediaServerLocalDescFailedError53401Server is unable to create or apply a local media description
TVOErrorMediaClientRemoteDescFailedError53402Client is unable to apply a remote media description
TVOErrorMediaServerRemoteDescFailedError53403Server is unable to apply a remote media description
TVOErrorMediaNoSupportedCodecError53404No supported codec
TVOErrorMediaConnectionError53405Media connection failed

Insights

Group NameEvent NameDescriptionSince version
connectionaccepted-by-localCall invite accepted3.0.0-beta2

If connection fails then an error event will be published.

Group NameEvent NameDescriptionSince version
connectionerrorerror description3.0.0-beta2

An example of using the acceptWithDelegate: API

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

// property declarations

@end

@implementation CallViewController

// ViewController setup and other code ...

- (void)callInviteReceived:(TVOCallInvite *)callInvite {
    self.call = [callInvite acceptWithDelegate:self];
}

#pragma mark - TVOCallDelegate

- (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

See Also

Declared In

TVOCallInvite.h

– acceptWithOptions:delegate:

Accepts the incoming Call Invite.

- (nonnull TVOCall *)acceptWithOptions:(nonnull TVOAcceptOptions *)options delegate:(nonnull id<TVOCallDelegate>)delegate

Parameters

options

An accept options.

delegate

A TVOCallDelegate to receive Call state updates.

Return Value

A TVOCall object.

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 TVOCallDelegate will receive the Call state update callbacks. The callbacks are same as acceptWithDelegate: API.

If accept 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 acceptWithDelegate: API.

Insights

Group NameEvent NameDescriptionSince version
connectionaccepted-by-localCall invite accepted3.0.0-beta2

If connection fails then an error event will be published.

Group NameEvent NameDescriptionSince version
connectionerrorerror description3.0.0-beta2

An example of using the acceptWithOptions:delegate: API

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

// property declarations

@end

@implementation CallViewController

// ViewController setup and other code ...

- (void)callInviteReceived:(TVOCallInvite *)callInvite {
    TVOAcceptOptions *options = [TVOAcceptOptions optionsWithCallInvite:callInvite
                                                                  block:^(TVOAcceptOptionsBuilder *builder) {
        builder.uuid = callInvite.uuid;
    }];
    self.call = [callInvite acceptWithOptions:options delegate:self];
}

#pragma mark - TVOCallDelegate

- (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

Declared In

TVOCallInvite.h

– reject

Rejects the incoming Call Invite.

- (void)reject

Declared In

TVOCallInvite.h

– init

Call Invites cannot be instantiated directly. See TVONotificationDelegate instead.

- (null_unspecified instancetype)init

Declared In

TVOCallInvite.h

CallKit Methods

  uuid

UUID of the Call Invite.

@property (nonatomic, copy, readonly, nonnull) NSUUID *uuid

Discussion

Use this UUID for CallKit methods. Accepting a TVOCallInvite yields a TVOCall which inherits its UUID from the Invite.

Declared In

TVOCallInvite.h