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()
.
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.
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()
3.0.0-beta8