Class Call


  • public class Call
    extends java.lang.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
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Call.CallQualityWarning  
      static class  Call.Issue
      An enum representing issue type associated with a call.
      static interface  Call.Listener
      Call.Listener interface defines a set of callbacks for events related to call.
      static class  Call.Score
      An enum representing call quality score.
      static class  Call.State
      An enum describing the possible states of a Call.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void disconnect()
      Disconnects the Call.
      java.util.Set<Call.CallQualityWarning> getCallQualityWarnings()
      Get current set of Call quality warnings.
      java.lang.String getFrom()
      Returns the caller information when available.
      java.lang.String getSid()
      Returns the call sid.
      Call.State getState()
      Returns the current state of the call.
      void getStats​(StatsListener statsListener)
      Retrieve stats for all media tracks and notify StatsListener via calling thread.
      java.lang.String getTo()
      Returns the callee information when available.
      void hold​(boolean hold)
      Holds or un-holds the audio.
      boolean isMuted()
      Reports whether the audio input is muted.
      boolean isOnHold()
      Reports whether the call is on hold.
      void mute​(boolean mute)
      Mutes or unmutes the audio input.
      void onError​(VoiceException voiceException)  
      void postFeedback​(Call.Score score, Call.Issue issue)
      Posts the feedback collected for this call to Twilio.
      void sendDigits​(java.lang.String digits)
      Sends a string of DTMF digits.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • getFrom

        @Nullable
        public java.lang.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 java.lang.String getTo()
        Returns the callee information when available. Returns null for an outgoing call.
      • getSid

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

        public void getStats​(@NonNull
                             StatsListener statsListener)
        Retrieve stats for all media tracks and notify StatsListener via calling thread. In case where call is in Call.State.DISCONNECTED state, reports won't be delivered.
        Parameters:
        statsListener - listener that receives stats reports for all media tracks.
      • 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
                               java.lang.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.