public class Call
extends InternalCall
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
Call
s 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 Scenario | Call.Listener callbacks |
Call.State transitions |
A Call is initiated and the caller disconnects before reaching the Call.State.RINGING state. |
||
A Call is initiated, reaches the Call.State.RINGING state, and the caller disconnects before being Call.State.CONNECTED . |
||
A Call is initiated and the Call fails to connect before reaching the Call.State.RINGING state. |
||
A Call is initiated and the Call fails to connect after reaching the Call.State.RINGING state. |
||
A Call is initiated, becomes Call.State.CONNECTED , and ends for one of the following reasons:
|
The following table provides expected call sequences for common scenarios from the callee perspective:
Callee Scenario | Call.Listener callbacks | Call.State transitions |
A CallInvite is accepted and the callee disconnects the Call before being Call.State.CONNECTED . |
||
A CallInvite is accepted and the Call fails to reach the Call.State.CONNECTED state. |
||
A CallInvite is accepted, becomes Call.State.CONNECTED , and ends for one of the following reasons:
|
||
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.
Note SDK will always raise a `onReconnecting()` callback followed by a `onReconnected()` callback when reconnection is successful.
During the reconnecting state operations such ashold(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
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
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 |
The following ICE connection state events are reported to Insights during a Call
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
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
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 network quality warning and network quality warning cleared events are reported to Insights during a Call
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
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-raised | constant-audio-output-level | Last ten audio output samples have the same audio level | 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
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 |
Modifier and Type | Class and Description |
---|---|
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.
|
Modifier and Type | Method and Description |
---|---|
void |
disconnect()
Disconnects the Call.
|
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 |
postFeedback(Call.Score score,
Call.Issue issue)
Posts the feedback collected for this call to Twilio.
|
void |
sendDigits(String digits)
Sends a string of DTMF digits.
|
public String getFrom()
null
for an outgoing call
and may be null
if it was not provided in the CallInvite
for an incoming call.public String getTo()
public String getSid()
Call.State.RINGING
state.public Call.State getState()
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.
public void getStats(StatsListener statsListener)
StatsListener
via calling thread.
In case where call is in Call.State.DISCONNECTED
state, reports won't be delivered.statsListener
- listener that receives stats reports for all media tracks.public void postFeedback(Call.Score score, Call.Issue issue)
score
- - the call quality score.issue
- - the issue type associated with the call.public void mute(boolean mute)
public void sendDigits(String digits)
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.public void hold(boolean hold)
public boolean isMuted()
public boolean isOnHold()
public void disconnect()
Invoking disconnect will result in a subsequent Call.Listener.onDisconnected(Call, CallException)
being raised unless any of the following conditions are true:
Call.Listener.onDisconnected(Call, CallException)
will be raisedCall.State.DISCONNECTED
MessageListener.onCancelledCallInvite(CancelledCallInvite, CallException)
with a CancelledCallInvite
with the same call SID of the call object5.2.0