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.

Insights

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

Group NameEvent NameDescriptionSince version
connectionmutedAudio input of the call is muted by calling [TVOCall setMuted:] with YES.3.0.0-beta2
connectionunmutedAudio input of the call is unmuted by calling [TVOCall setMuted:] with NO.3.0.0-beta2
connectionaccepted-by-remoteServer returns an answer to the Client’s offer over the signaling channel.3.0.0-beta2
connectionringingCall state transitions to TVOCallStateRinging.3.0.0-beta2
connectionconnectedCall state transitions to TVOCallStateConnected.3.0.0-beta2
connectiondisconnect-called[TVOCall disconnect] is called.3.0.0-beta2
connectiondisconnected-by-localCall disconnected as a result of calling [TVOCall disconnect]. Call transitions to TVOCallStateDisconnected.3.0.0-beta2
connectiondisconnected-by-remoteCall is disconnected by the remote. Call transitions to TVOCallStateDisconnected.3.0.0-beta2
connectionholdCall is on hold by calling [TVOCall setOnHold:] with YES.3.0.0-beta2
connectionunholdCall is on unhold by calling [TVOCall setOnHold:] with NO.3.0.0-beta2
connectionerrorError description. Call state transitions to TVOCallStateDisconnected.3.0.0-beta2

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

Group NameEvent NameDescriptionSince version
ice-connection-statenewThe PeerConnection ice connection state changed to “new”.3.0.0-beta3
ice-connection-statecheckingThe PeerConnection ice connection state changed to “checking”.3.0.0-beta3
ice-connection-stateconnectedThe PeerConnection ice connection state changed to “connected”.3.0.0-beta3
ice-connection-statecompletedThe PeerConnection ice connection state changed to “completed”.3.0.0-beta3
ice-connection-stateclosedThe PeerConnection ice connection state changed to “closed”.3.0.0-beta3
ice-connection-statedisconnectedThe PeerConnection ice connection state changed to “disconnected”.3.0.0-beta3
ice-connection-statefailedThe PeerConnection ice connection state changed to “failed”.3.0.0-beta3

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

Group NameEvent NameDescriptionSince version
ice-gathering-statenewThe PeerConnection ice gathering state changed to “new”.3.0.0-beta3
ice-gathering-stategatheringThe PeerConnection ice gathering state changed to “checking”.3.0.0-beta3
ice-gathering-statecompleteThe PeerConnection ice gathering state changed to “connected”.3.0.0-beta3

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

Group NameEvent NameDescriptionSince version
signaling-statestableThe PeerConnection signaling state changed to “stable”.3.0.0-beta3
signaling-statehave-local-offerThe PeerConnection signaling state changed to “have-local-offer”.3.0.0-beta3
signaling-statehave-remote-offersThe PeerConnection signaling state changed to “have-remote-offers”.3.0.0-beta3
signaling-statehave-local-pranswerThe PeerConnection signaling state changed to “have-local-pranswer”.3.0.0-beta3
signaling-statehave-remote-pranswerThe PeerConnection signaling state changed to “have-remote-pranswer”.3.0.0-beta3
signaling-stateclosedThe PeerConnection signaling state changed to “closed”.3.0.0-beta3

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

Group NameEvent NameDescriptionSince version
network-quality-warning-raisedhigh-jitterThree out of last five jitter samples exceed 30 ms.3.0.0-beta3
network-quality-warning-clearedhigh-jitterhigh-jitter warning cleared if last five jitter samples are less than 30 ms.3.0.0-beta3
network-quality-warning-raisedlow-mosThree out of last five mos samples are lower than 3.3.0.0-beta3
network-quality-warning-clearedlow-moslow-mos cleared if last five mos samples are higher than 3.3.0.0-beta3
network-quality-warning-raisedhigh-packet-lossThree out of last five packet loss samples show loss greater than 1%.3.0.0-beta3
network-quality-warning-clearedhigh-packet-losshigh-packet-loss cleared if last five packet loss samples are lower than 1%.3.0.0-beta3
network-quality-warning-raisedhigh-rttThree out of last five RTT samples show greater than 400 ms.3.0.0-beta3
network-quality-warning-clearedhigh-rtthigh-rtt warning cleared if last five RTT samples are lower than 400 ms.3.0.0-beta3

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

Group NameEvent NameDescriptionSince version
audio-level-warning-raisedconstant-audio-input-levelLast ten audio input samples have the same audio level3.0.0-beta3
audio-level-warning-clearedconstant-audio-input-levelconstant-audio-input-level warning cleared if the current audio input level sample differs from the previous audio input level sample3.0.0-beta3
audio-level-warning-raisedconstant-audio-output-levelLast ten audio output samples have the same audio level3.0.0-beta3
audio-level-warning-clearedconstant-audio-output-levelconstant-audio-output-level warning cleared if the current audio output level sample differs from the previous audio output level sample3.0.0-beta3

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

Group NameEvent NameDescriptionSince version
feedbackreceived[TVOCall postFeedback:issue:] is called if the score is not TVOCallFeedbackScoreNotReported or the issue type is not TVOCallFeedbackIssueNotReported.3.0.0-beta3
feedbackreceived-none[TVOCall postFeedback:issue:] is called if the score is TVOCallFeedbackScoreNotReported and the issue type is TVOCallFeedbackIssueNotReported.3.0.0-beta3

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