TVOCall Class Reference

Inherits from NSObject
Declared in TVOCall.h

Overview

The TVOCall class represents a signaling and media session between the host device and Twilio infrastructure. Calls can represent an outbound call initiated from the SDK via [TwilioVoice connectWithAccessToken:delegate:] or an incoming call accepted via a [TVOCallInvite acceptWithDelegate:]. Devices that initiate an outbound call represent the caller and devices that receive a TVOCallInvite represent the callee.

The lifecycle of a call differs for the caller and the callee. Making or accepting a call requires a TVOCallDelegate which receives call state changes defined in TVOCallState. The TVOCallState can be obtained at any time from the state property of TVOCall.

The caller callback behavior is affected by the answerOnBridge flag provided in the Dial verb of your TwiML application associated with this client. If the answerOnBridge flag is false, which is the default, the [TVOCallDelegate callDidConnect:] callback will be emitted immediately after [TVOCallDelegate callDidStartRinging:]. If the answerOnBridge flag is true this will cause the call to emit the [TVOCallDelegate callDidConnect:] callback only until the call is answered. See Answer on Bridge documentation for more details on how to use it with the Dial TwiML verb.

The following table provides expected call sequences for common scenarios from the perspective of the caller:

ScenarioTVOCallDelegate CallbacksTVOCallState Transitions
A call is initiated and the caller disconnects before reaching the ringing state.
  1. [TVOCallDelegate call:didDisconnectWithError:]
  1. TVOCallStateConnecting
  2. TVOCallStateDisconnected
A call is initiated, reaches the ringing state and the caller disconnects before being connected.
  1. [TVOCallDelegate callDidStartRinging:]
  2. [TVOCallDelegate call:didDisconnectWithError:]
  1. TVOCallStateConnecting
  2. TVOCallStateRinging
  3. TVOCallStateDisconnected
A call is initiated and the call fails to connect before reaching the ringing state.
  1. [TVOCallDelegate call:didFailToConnectWithError:]
  1. TVOCallStateConnecting
  2. TVOCallStateDisconnected
A call is initiated and the call fails to connect after reaching the ringing state.
  1. [TVOCallDelegate callDidStartRinging:]
  2. [TVOCallDelegate call:didFailToConnectWithError:]
  1. TVOCallStateConnecting
  2. TVOCallStateRinging
  3. TVOCallStateDisconnected
A call is initiated, becomes connected, and ends for one of the following reasons:
  • The caller disconnects the call
  • The callee disconnects the call
  • An on-device error occurs. (eg. network loss)
  • An error between the caller and callee occurs. (eg. media connection lost or Twilio infrastructure failure)
  1. [TVOCallDelegate callDidStartRinging:]
  2. [TVOCallDelegate callDidConnect:]
  3. [TVOCallDelegate call:didDisconnectWithError:]
  1. TVOCallStateConnecting
  2. TVOCallStateRinging
  3. TVOCallStateConnected
  4. TVOCallStateDisconnected

The following table provides expected call sequences for common scenarios from the callee perspective:

ScenarioTVOCallDelegate CallbacksTVOCallState Transitions
A TVOCallInvite is accepted and the callee disconnects the call before being connected.
  1. [TVOCallDelegate call:didDisconnectWithError:]
  1. TVOCallStateConnecting
  2. TVOCallStateDisconnected
A TVOCallInvite is accepted and the call fails to connect.
  1. [TVOCallDelegate call:didFailToConnectWithError:]
  1. TVOCallStateConnecting
  2. TVOCallStateDisconnected
A TVOCallInvite is accepted, becomes connected, and ends for one of the following reasons:
  • The caller disconnects the call
  • The callee disconnects the call
  • An on-device error occurs. (eg. network loss)
  • An error between the caller and callee occurs. (eg. media connection lost or Twilio infrastructure failure)
  1. [TVOCallDelegate callDidStartRinging:]
  2. [TVOCallDelegate callDidConnect:]
  3. [TVOCallDelegate call:didDisconnectWithError:]
  1. TVOCallStateConnecting
  2. TVOCallStateRinging
  3. TVOCallStateConnected
  4. TVOCallStateDisconnected

It is important to call the [TVOCall disconnect] method to terminate the call. Not calling [TVOCall disconnect] results in leaked native resources and may lead to an out-of-memory crash. If the call is disconnected by the caller, callee, or Twilio, the SDK will automatically free native resources. However, [TVOCall disconnect] is an idempotent operation so it is best to call this method when you are certain your application no longer needs the object.

It is strongly recommended that <TVOCall> instances are created and accessed from a single dispatch queue. Accessing a <TVOCall> instance from multiple queues may cause synchronization problems. TVOCallDelegate methods are called on the main dispatch queue by default or on the delegateQueue provided to TVOConnectOptions or TVOAcceptOptions upon initiating or accepting a call.

Properties

  from

From value of the Call.

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

Discussion

This may be nil if the call object was created by calling the [TwilioVoice connectWithOptions:delegate:] method or if the call object was created by calling the [TVOCallInvite acceptWithOptions:delegate:] method where the from value of the TVOCallInvite object was also nil.

Declared In

TVOCall.h

  to

To value of the Call.

@property (nonatomic, strong, readonly, nullable) NSString *to

Discussion

This may be nil if the call object was created by calling the [TwilioVoice connectWithOptions:delegate:] method.

Declared In

TVOCall.h

  sid

A server assigned identifier (SID) for the Call.

@property (nonatomic, strong, readonly, nonnull) NSString *sid

Discussion

A SID is a globally unique identifier which can be very useful for debugging Call traffic. The Call sid may be nil until the call is in TVOCallStateRinging state.

Declared In

TVOCall.h

  muted

Property that defines if the Call is muted.

@property (nonatomic, assign, getter=isMuted) BOOL muted

Discussion

The Voice SDK’s media engine will start sending silent audio frames when the Call is muted. Setting the property will only take effect if the state is TVOCallStateConnected.

Declared In

TVOCall.h

  state

The current state of the Call.

@property (nonatomic, assign, readonly) TVOCallState state

Discussion

All TVOCall instances start in TVOCallStateConnecting and end in TVOCallStateDisconnected. After creation, a Call will transition to TVOCallStateConnected if successful or TVOCallStateDisconnected if the connection attempt fails.

See Also

Declared In

TVOCall.h

  onHold

Property that defines if the Call is on hold.

@property (nonatomic, getter=isOnHold) BOOL onHold

Discussion

If the Call is on hold, The Voice SDK’s media engine will send silent audio frames to the remote party, and remote party’s audio playback will be disabled.

Declared In

TVOCall.h

General Call Actions

– disconnect

Disconnects the Call.

- (void)disconnect

Discussion

Calling this method on a TVOCall that is in the state TVOCallStateDisconnected has no effect.

Declared In

TVOCall.h

– sendDigits:

Send a string of digits.

- (void)sendDigits:(nonnull NSString *)digits

Parameters

digits

A string of characters to be played. Valid values are ‘0’ - ‘9’, ‘*’, ‘#’, and ‘w’. Each ‘w’ will cause a 500 ms pause between digits sent.

Discussion

Calling this method on a TVOCall that is not in the state TVOCallStateConnected has no effect.

Declared In

TVOCall.h

– getStatsWithBlock:

Retrieve stats for the audio track.

- (void)getStatsWithBlock:(nonnull TVOCallGetStatsBlock)block

Parameters

block

The block to be invoked when the stats are available.

Declared In

TVOCall.h

– postFeedback:issue:

Posts the feedback collected for this Call to Twilio.

- (void)postFeedback:(TVOCallFeedbackScore)score issue:(TVOCallFeedbackIssue)issue

Parameters

score

The quality score of the Call.
issue

The issue associated with the Call.

Discussion

If TVOCallFeedbackScoreNotReported and TVOCallFeedbackIssueNotReported are passed, Twilio will report feedback was not available for this call.

See Also

Declared In

TVOCall.h

CallKit Methods

  uuid

A unique identifier for the Call.

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

Discussion

Use this UUID as an argument to CallKit methods. You can provide a UUID for outgoing calls using [TwilioVoice connectWithOptions:delegate:]. Calls created via [TVOCallInvite acceptWithOptions:delegate:] inherit their uuid from the Invite itself.

Declared In

TVOCall.h