Package com.twilio.voice

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

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

Callee Call Sequences

Callee Scenario	Call.Listener callbacks	Call.State transitions
A CallInvite is accepted and the callee disconnects the Call before being Call.State.CONNECTED.	Call.Listener.onDisconnected(Call, CallException)	Call.State.CONNECTING Call.State.DISCONNECTED
A CallInvite is accepted and the Call fails to reach the Call.State.CONNECTED state.	Call.Listener.onConnectFailure(Call, CallException)	Call.State.CONNECTING 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)	Call.Listener.onConnected(Call) Call.Listener.onDisconnected(Call, CallException)	Call.State.CONNECTING Call.State.CONNECTED 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 Name	Event Name	Description	Since version
connection	muted	The audio input of the Call is muted by calling mute(boolean) with true	3.0.0-beta2
connection	unmuted	The audio input of the Call is unmuted by calling mute(boolean) with false	3.0.0-beta2
connection	accepted-by-remote	The server returned an answer to the offer over the signaling channel	3.0.0-beta2
connection	ringing	The Call state transitions to Call.State.RINGING	3.0.0-beta2
connection	connected	The Call state transitions to Call.State.CONNECTED	3.0.0-beta2
connection	disconnect-called	The disconnect() method was called	3.0.0-beta2
connection	disconnected-by-local	The Call disconnected as a result of calling disconnect(). Call.State transitions to Call.State.DISCONNECTED	3.0.0-beta2
connection	disconnected-by-remote	The Call was disconnected by the server. Call.State transitions to Call.State.DISCONNECTED	3.0.0-beta2
connection	hold	The Call is on hold by calling hold(boolean)	3.0.0-beta2
connection	unhold	The Call is unhold by calling hold(boolean)	3.0.0-beta2
connection	error	Error description. The Call state transitions to Call.State.DISCONNECTED	3.0.0-beta2
connection	reconnecting	The Call is attempting to recover from a signaling or media connection interruption	3.0.0-beta3
connection	reconnected	The Call has recovered from a signaling or media connection interruption	3.0.0-beta3

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

Insights ICE candidate event

Group Name	Event Name	Description	Since version
ice-candidate	ice-candidate	ICE candidate events are raised when OnIceCandidate is called on the PeerConnection	4.1.0
ice-candidate	selected-ice-candidate-pair	The active local ICE candidate and remote ICE candidate	5.5.0

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

Insights ICE connection events

Group Name	Event Name	Description	Since version
ice-connection-state	new	The PeerConnection ice connection state changed to "new"	3.0.0-beta3
ice-connection-state	checking	The PeerConnection ice connection state changed to "checking"	3.0.0-beta3
ice-connection-state	connected	The PeerConnection ice connection state changed to "connected"	3.0.0-beta3
ice-connection-state	completed	The PeerConnection ice connection state changed to "completed"	3.0.0-beta3
ice-connection-state	closed	The PeerConnection ice connection state changed to “closed”	3.0.0-beta3
ice-connection-state	disconnected	The PeerConnection ice connection state changed to “disconnected”	3.0.0-beta3
ice-connection-state	failed	The 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 Name	Event Name	Description	Since version
ice-gathering-state	new	The PeerConnection ice gathering state changed to "new"	3.0.0-beta3
ice-gathering-state	gathering	The PeerConnection ice gathering state changed to "checking"	3.0.0-beta3
ice-gathering-state	complete	The 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 Name	Event Name	Description	Since version
signaling-state	stable	The PeerConnection signaling state changed to "stable"	3.0.0-beta3
signaling-state	have-local-offer	The PeerConnection signaling state changed to "have-local-offer"	3.0.0-beta3
signaling-state	have-remote-offers	The PeerConnection signaling state changed to "have-remote-offers"	3.0.0-beta3
signaling-state	have-local-pranswer	The PeerConnection signaling state changed to "have-local-pranswer"	3.0.0-beta3
signaling-state	have-remote-pranswer	The PeerConnection signaling state changed to “have-remote-pranswer”	3.0.0-beta3
signaling-state	closed	The 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 Name	Event Name	Description	Since version
pc-connection-state	new	The PeerConnection state is "new"	5.4.0
pc-connection-state	connecting	The PeerConnection state changed to "connecting"	5.4.0
pc-connection-state	connected	The PeerConnection state changed to "connected"	5.4.0
pc-connection-state	disconnected	Raised when peer connection state is disconnected	5.4.0
pc-connection-state	failed	Raised when peer connection state is failed	5.4.0
pc-connection-state	closed	Raised when peer connection state is closed	5.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 Name	Event Name	Description	Since version
network-quality-warning-raised	high-jitter	Three out of last five jitter samples exceed 30 ms	3.0.0-beta3
network-quality-warning-cleared	high-jitter	high-jitter warning cleared if last five jitter samples are less than 30 ms	3.0.0-beta3
network-quality-warning-raised	low-mos	Three out of last five mos samples are lower than 3	3.0.0-beta3
network-quality-warning-cleared	low-mos	low-mos cleared if last five mos samples are higher than 3	3.0.0-beta3
network-quality-warning-raised	high-packet-loss	Three out of last five packet loss samples show loss greater than 1%	3.0.0-beta3
network-quality-warning-cleared	high-packet-loss	high-packet-loss cleared if last five packet loss samples are lower than 1%	3.0.0-beta3
network-quality-warning-raised	high-rtt	Three out of last five RTT samples show greater than 400 ms	3.0.0-beta3
network-quality-warning-cleared	high-rtt	high-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

Insights audio level events

Group Name	Event Name	Description	Since version
audio-level-warning-raised	constant-audio-input-level	Last ten audio input samples have the same audio level	3.0.0-beta3
audio-level-warning-cleared	constant-audio-input-level	constant-audio-input-level warning cleared if the current audio input level sample differs from the previous audio input level sample	3.0.0-beta3
audio-level-warning-cleared	constant-audio-output-level	constant-audio-output-level warning cleared if the current audio output level sample differs from the previous audio output level sample	3.0.0-beta3

The following feedback events are reported to Insights during a Call

Insights feedback events

Group Name	Event Name	Description	Since version
feedback	received	postFeedback(Score, Issue) is called with a score other than Call.Score.NOT_REPORTED or an issue other than Call.Issue.NOT_REPORTED i	3.0.0-beta3
feedback	received-none	postFeedback(Score, Issue) is called with Call.Score.NOT_REPORTED and Call.Issue.NOT_REPORTED	3.0.0-beta3

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Call.CallMessageListener	Call.CallMessageListener interface defines a set of callbacks when CallMessage is received or when the result of outbound CallMessage request is available.
static enum	Call.CallQualityWarning
static enum	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 enum	Call.Score	An enum representing call quality score.
static enum	Call.State	An enum describing the possible states of a Call.

Method Summary

Modifier and Type	Method	Description
void	disconnect()	Disconnects the Call.
Set<Call.CallQualityWarning>	getCallQualityWarnings()	Get current set of Call quality warnings.
String	getFrom()	Returns the caller information when available.
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.
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	release()
void	sendDigits(String digits)	Sends a string of DTMF digits.
String	sendMessage(CallMessage message)	Sends a user-defined message to endpoints that have subscribed for user-defined messages.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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:

• Disconnect was already called on the call object. In this case, only one Call.Listener.onDisconnected(Call, CallException) will be raised
• The call is already Call.State.DISCONNECTED
• The call has been cancelled. In this case, the application has already received a MessageListener.onCancelledCallInvite(CancelledCallInvite, CallException) with a CancelledCallInvite with the same call SID of the call object

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, 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)