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.

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 [TwilioVoiceSDK handleNotification:delegate:delegateQueue:callMessageDelegate:] 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"?>
<Response>
  <Dial callerId="client:alice">
    <Client>
      <Identity>bob</Identity>
      <Parameter name="caller_first_name" value="alice" />
      <Parameter name="caller_last_name" value="smith" />
    </Client>
  </Dial>
</Response>

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

  callerInfo

The TVOCallerInfo that represents SHAKEN/STIR status information about the caller.

@property (nonatomic, strong, readonly, nonnull) TVOCallerInfo *callerInfo

See Also

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
TVOErrorTransportError31009Transport error
TVOErrorAuthorizationError31201Authorization error
TVOErrorForbiddenError31403Forbidden
TVOErrorRequestTimeoutError31408Request Timeout
TVOErrorCallDoesNotExistError31481Call/Transaction Does Not Exist
TVOErrorRequestTerminatedError31487Request Terminated
TVOErrorInternalServerError31500Internal Server Error
TVOErrorBadGatewayError31502Bad Gateway
TVOErrorServiceUnavailableError31503Service Unavailable
TVOErrorGatewayTimeoutError31504Gateway Timeout
TVOErrorDNSResolutionError31530DNS Resolution Error
TVOErrorDoesNotExistAnywhereError31604Does Not Exist Anywhere
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
TVOMediaDtlsTransportFailedErrorCode53407Media connection failed due to DTLS handshake failure

Insights

Group NameEvent NameDescriptionSince version
connectionaccepted-by-localCall invite accepted3.0.0-beta2
settingscodecnegotiated selected codec is received and remote SDP is set5.1.1

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.

Insights

Group NameEvent NameDescriptionSince version
connectionrejected-by-localCall invite rejected3.0.0-preview5
connectionerrorThe event will be sent with code 31600 and message “Busy Everywhere : SIP/2.0 600 Call Rejected”3.1.0

- (void)reject

Declared In

TVOCallInvite.h

– sendMessage:

Sends a user-defined message to the endpoints that subscribe to the user-defined messages of this Call Invite.

- (nonnull NSString *)sendMessage:(nonnull TVOCallMessage *)callMessage

Parameters

callMessage

The TVOCallMessage object with the message and configuration.

Return Value

A unique identifier for tracking the message.

Discussion

The result will be raised to the TVOCallMessageDelegate provided in the [TwilioVoiceSDK handleNotification:delegate:delegateQueue:callMessageDelegate:] on the same dispatch queue. Dispatch main queue will be used if not specified.

Sending a call message with content size that exceeds 10 KB or sending more than 10 call messages within one minute will result in the [TVOCallMessageDelegate call:didFailToSendMessage:error] callback.

A call message with content that does not match the content type will not result in the [TVOCallMessageDelegate call:didFailToSendMessage:error] callback but will generate an error in your Twilio developer console. For example, a call message with content type “application/json” but with the content “Hello World”, which is not a valid JSON object, will result in such error.

A subscription with a user-defined message callback is required prior to calling this method. Calling the [TVOCallInvite sendMessage:] method without subscribing first will result in an error in your Twilio developer console.

This method returns an empty string and will not send out the Call Message if the Call Invite has been accepted or rejected.

This feature is currently in Beta.

Declared In

TVOCallInvite.h

– init

Call Invites cannot be instantiated directly. See TVONotificationDelegate instead.

- (null_unspecified instancetype)init

Declared In

TVOCallInvite.h