Class Call

java.lang.Object
com.twilio.voice.Call

public class Call extends Object
The Call 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 Voice.connect(...) or an incoming call accepted via a CallInvite. Devices that initiate an outbound call represent the caller and devices that receive a CallInvite represent the callee.

The lifecycle of a call differs for the caller and the callee. Making or accepting a call requires a Call.Listener which provides Call state changes defined in Call.State. The Call.State can be obtained at any time by calling getState().

A subset of Android devices provide an OpenSLES implementation. Although more efficient, the use of OpenSLES occasionally results in echo. As a result, the Voice SDK disables OpenSLES by default for both incoming and outgoing Calls unless explicitly enabled. To enable OpenSLES execute the following before invoking Voice.connect(Context, ConnectOptions, Listener) or CallInvite.accept(Context, Listener):

tvo.webrtc.voiceengine.WebRtcAudioManager.setBlacklistDeviceForOpenSLESUsage(false)

The following table provides expected call sequences for common scenarios from the caller perspective. The caller scenario sequences are affected by the answerOnBridge flag provided in the Dial verb of your TwiML application associated with the client. If the answerOnBridge flag is false, which is the default, the Call.Listener.onConnected(Call) callback will be emitted immediately after Call.Listener.onRinging(Call). If the answerOnBridge flag is true this will cause the call to emit the Call.Listener.onConnected(Call) callback only until the call is answered by the callee. See the Answer on Bridge documentation for more details on how to use it with the Dial TwiML verb.

Caller Call Sequences
Caller Scenario Call.Listener callbacks Call.State transitions
A Call is initiated and the caller disconnects before reaching the Call.State.RINGING state.
  1. Call.Listener.onDisconnected(Call, CallException)
  1. Call.State.CONNECTING
  2. Call.State.DISCONNECTED
A Call is initiated, reaches the Call.State.RINGING state, and the caller disconnects before being Call.State.CONNECTED.
  1. Call.Listener.onRinging(Call)
  2. Call.Listener.onDisconnected(Call, CallException)
  1. Call.State.CONNECTING
  2. Call.State.RINGING
  3. Call.State.DISCONNECTED
A Call is initiated and the Call fails to connect before reaching the Call.State.RINGING state.
  1. Call.Listener.onConnectFailure(Call, CallException)
  1. Call.State.CONNECTING
  2. Call.State.DISCONNECTED
A Call is initiated and the Call fails to connect after reaching the Call.State.RINGING state.
  1. Call.Listener.onRinging(Call)
  2. Call.Listener.onConnectFailure(Call, CallException)
  1. Call.State.CONNECTING
  2. Call.State.RINGING
  3. Call.State.DISCONNECTED
A Call is initiated, becomes Call.State.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. Call.Listener.onRinging(Call)
  2. Call.Listener.onConnected(Call)
  3. Call.Listener.onDisconnected(Call, CallException)
  1. Call.State.CONNECTING
  2. Call.State.RINGING
  3. Call.State.CONNECTED
  4. Call.State.DISCONNECTED

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

Callee Call Sequences
Callee ScenarioCall.Listener callbacksCall.State transitions
A CallInvite is accepted and the callee disconnects the Call before being Call.State.CONNECTED.
  1. Call.Listener.onDisconnected(Call, CallException)
  1. Call.State.CONNECTING
  2. Call.State.DISCONNECTED
A CallInvite is accepted and the Call fails to reach the Call.State.CONNECTED state.
  1. Call.Listener.onConnectFailure(Call, CallException)
  1. Call.State.CONNECTING
  2. Call.State.DISCONNECTED
A CallInvite is accepted, becomes Call.State.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. Call.Listener.onConnected(Call)
  2. Call.Listener.onDisconnected(Call, CallException)
  1. Call.State.CONNECTING
  2. Call.State.CONNECTED
  3. Call.State.DISCONNECTED
A CallInvite is rejected. Reject will not result in any callbacks. The call invite was not accepted, therefore the Call.State is not available.

It is important to call the disconnect() method to terminate the call. Not calling 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, 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 Call instances are created and accessed from a single application thread. Accessing an instance from multiple threads may cause synchronization problems. Listeners are called on the thread that created the Call instance, unless the thread that created the Call instance does not have a Looper. In that case, the listener will be called on the application's main thread.

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 `onReconnecting()` and `onReconnected()` callbacks. For example, a network change may result in the following callback sequence.

  • onReconnecting() with `CallException` with `EXCEPTION_SIGNALING_CONNECTION_DISCONNECTED` error code
  • onReconnected()
  • onReconnecting() with `CallException` with `EXCEPTION_MEDIA_CONNECTION_FAILED` error code
  • onReconnected()

Note SDK will always raise a `onReconnecting()` callback followed by a `onReconnected()` callback when reconnection is successful.

During the reconnecting state operations such as hold(boolean), mute(boolean), or sendDigits(String) 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

Insights connection events
Group NameEvent NameDescriptionSince version
connectionmutedThe audio input of the Call is muted by calling mute(boolean) with true3.0.0-beta2
connectionunmutedThe audio input of the Call is unmuted by calling mute(boolean) with false3.0.0-beta2
connectionaccepted-by-remoteThe server returned an answer to the offer over the signaling channel3.0.0-beta2
connectionringingThe Call state transitions to Call.State.RINGING3.0.0-beta2
connectionconnectedThe Call state transitions to Call.State.CONNECTED3.0.0-beta2
connectiondisconnect-calledThe disconnect() method was called3.0.0-beta2
connectiondisconnected-by-localThe Call disconnected as a result of calling disconnect(). Call.State transitions to Call.State.DISCONNECTED3.0.0-beta2
connectiondisconnected-by-remoteThe Call was disconnected by the server. Call.State transitions to Call.State.DISCONNECTED3.0.0-beta2
connectionholdThe Call is on hold by calling hold(boolean)3.0.0-beta2
connectionunholdThe Call is unhold by calling hold(boolean)3.0.0-beta2
connectionerrorError description. The Call state transitions to Call.State.DISCONNECTED3.0.0-beta2
connectionreconnectingThe Call is attempting to recover from a signaling or media connection interruption3.0.0-beta3
connectionreconnectedThe Call has recovered from a signaling or media connection interruption3.0.0-beta3

The following ICE candidate event is reported to Insights during a Call

Insights ICE candidate event
Group NameEvent NameDescriptionSince version
ice-candidateice-candidateICE candidate events are raised when OnIceCandidate is called on the PeerConnection4.1.0
ice-candidateselected-ice-candidate-pairThe active local ICE candidate and remote ICE candidate5.5.0

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

Insights ICE connection events
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

Insights ICE gathering events
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

Insights peer connection signaling state events
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 peer connection state events are reported to Insights during a Call

Insights peer connection state events
Group NameEvent NameDescriptionSince version
pc-connection-statenewThe PeerConnection state is "new"5.4.0
pc-connection-stateconnectingThe PeerConnection state changed to "connecting"5.4.0
pc-connection-stateconnectedThe PeerConnection state changed to "connected"5.4.0
pc-connection-statedisconnectedRaised when peer connection state is disconnected5.4.0
pc-connection-statefailedRaised when peer connection state is failed5.4.0
pc-connection-stateclosedRaised when peer connection state is closed5.4.0

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

Insights network quality events
Group NameEvent NameDescriptionSince version
network-quality-warning-raisedhigh-jitterThree out of last five jitter samples exceed 30 ms3.0.0-beta3
network-quality-warning-clearedhigh-jitterhigh-jitter warning cleared if last five jitter samples are less than 30 ms3.0.0-beta3
network-quality-warning-raisedlow-mosThree out of last five mos samples are lower than 33.0.0-beta3
network-quality-warning-clearedlow-moslow-mos cleared if last five mos samples are higher than 33.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 ms3.0.0-beta3
network-quality-warning-clearedhigh-rtthigh-rtt warning cleared if last five RTT samples are lower than 400 ms3.0.0-beta3

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

Insights audio level events
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-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

Insights feedback events
Group NameEvent NameDescriptionSince version
feedbackreceivedpostFeedback(Score, Issue) is called with a score other than Call.Score.NOT_REPORTED or an issue other than Call.Issue.NOT_REPORTED i3.0.0-beta3
feedbackreceived-nonepostFeedback(Score, Issue) is called with Call.Score.NOT_REPORTED and Call.Issue.NOT_REPORTED3.0.0-beta3
  • Method Details

    • getFrom

      @Nullable public String getFrom()
      Returns the caller information when available. The from field is null for an outgoing call and may be null if it was not provided in the CallInvite for an incoming call.
    • getTo

      @Nullable public String getTo()
      Returns the callee information when available. Returns null for an outgoing call.
    • getSid

      @Nullable public String getSid()
      Returns the call sid. The call sid is null until the call is in Call.State.RINGING state.
    • getState

      @NonNull public Call.State getState()
      Returns the current state of the call.

      Call is in Call.State.CONNECTING state when it is made or accepted.

      Call is in Call.State.RINGING state when it is ringing.

      Call transitions to Call.State.CONNECTED state when connected to Twilio.

      Call transitions to Call.State.DISCONNECTED state when disconnected.

      Returns:
      Provides the state of this call.
    • getStats

      public void getStats(@NonNull StatsListener statsListener)
      Retrieve stats for all media tracks and notify StatsListener via calling thread. The call needs to be in Call.State.CONNECTED state for reports to be delivered.
      Parameters:
      statsListener - listener that receives stats reports for all media tracks.
    • getCallQualityWarnings

      public Set<Call.CallQualityWarning> getCallQualityWarnings()
      Get current set of Call quality warnings.
      Returns:
      Provides the set of current Call.CallQualityWarning.
    • postFeedback

      public void postFeedback(@NonNull Call.Score score, @NonNull Call.Issue issue)
      Posts the feedback collected for this call to Twilio. If `0` `Score` and `not-reported` `Issue` are passed, Twilio will report feedback was not available for this call.
      Parameters:
      score - - the call quality score.
      issue - - the issue type associated with the call.
    • mute

      public void mute(boolean mute)
      Mutes or unmutes the audio input.
    • sendDigits

      public void sendDigits(@NonNull String digits)
      Sends a string of DTMF digits.
      Parameters:
      digits - A string of digits to be sent. Valid values are "0" - "9", "*", "#", and "w". Each "w" will cause a 500 ms pause between digits sent.
    • hold

      public void hold(boolean hold)
      Holds or un-holds the audio.
    • isMuted

      public boolean isMuted()
      Reports whether the audio input is muted.
    • isOnHold

      public boolean isOnHold()
      Reports whether the call is on hold.
    • disconnect

      public void disconnect()
      Disconnects the Call.

      Invoking disconnect will result in a subsequent Call.Listener.onDisconnected(Call, CallException) being raised unless any of the following conditions are true:

    • sendMessage

      public String sendMessage(CallMessage message)
      Sends a user-defined message to endpoints that have subscribed for user-defined messages. The result will be raised to the Call.CallMessageListener provided as a connect option at the time of connection construction. Calling the `sendMessage` method without subscribing first will result in an error in your Twilio developer console. 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 Call.CallMessageListener.onMessageFailure(String, String, VoiceException) callback. When attempting to send a message larger than 10k, the error will not show in the developer console.
      Parameters:
      message - The call message to send.
      Returns:
      An unique identifier for tracking the message.
    • release

      public void release()
    • onError

      public void onError(VoiceException voiceException)