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 [TwilioVoiceSDK 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:

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

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.

An ongoing call will automatically switch to a more preferred network type if one becomes available. The following are the network types listed in preferred order: ETHERNET, LOOPBACK, WIFI, VPN, and CELLULAR. For example, if a WIFI network becomes available whilst in a call that is using CELLULAR data, the call will automatically switch to using the WIFI network.

Media and signaling reconnections are handled independently. As a result, it is possible that a single network change event produces consecutive [TVOCallDelegate call:isReconnectingWithError:] and [TVOCallDelegate callDidReconnect:] callbacks. For example, a network change may result in the following callback sequence.

• [TVOCallDelegate call:isReconnectingWithError:] with error.code TVOErrorSignalingConnectionDisconnectedError.
• [TVOCallDelegate callDidReconnect:].
• [TVOCallDelegate call:isReconnectingWithError:] with error.code TVOErrorMediaConnectionError.
• [TVOCallDelegate callDidReconnect:].

Note that the SDK will always raise a [TVOCallDelegate call:isReconnectingWithError:] callback followed by a [TVOCallDelegate callDidReconnect:] callback when reconnection is successful.

During the reconnecting state operations such as [TVOCall setOnHold:], [TVOCall setMuted:], [TVOCall sendDigits:] will result in undefined behavior. When building applications, the recommended practice is to show a UI update when the Call enters reconnecting regardless of the cause, and then clear the UI update once the call has reconnected or disconnected.

Insights

The following connection events are reported to Insights during a call:

The following peer connection state events are reported to Insights during a call:

The following ICE candidate event is reported to Insights during a call:

The following ICE connection state events are reported to Insights during a call:

The following ICE gathering state events are reported to Insights during a call:

The following signaling state events are reported to Insights during a call:

The following network quality warning and network quality warning cleared events are reported to Insights during a call:

The following audio level warning and audio level warning cleared events are reported to Insights during a call

The following feedback events are reported to Insights during a call: