public abstract class Voice extends Object
Modifier and Type | Class and Description |
---|---|
static class |
Voice.RegistrationChannel |
Modifier and Type | Method and Description |
---|---|
static Call |
connect(android.content.Context context,
ConnectOptions connectOptions,
Call.Listener listener)
Creates and returns a new
Call . |
static Call |
connect(android.content.Context context,
String accessToken,
Call.Listener listener)
Creates and returns a new
Call . |
static void |
enableInsights(boolean enable)
Specify reporting statistics to Insights.
|
static AudioDevice |
getAudioDevice()
Returns the AudioDevice.
|
static LogLevel |
getLogLevel()
Returns the logging level for messages logged by the Voice SDK.
|
static LogLevel |
getModuleLogLevel(LogModule module)
Returns the logging level for messages logged by the specified LogModule.
|
static String |
getRegion()
Returns the region specified
region . |
static String |
getVersion()
Returns the version of the Voice SDK.
|
static boolean |
handleMessage(android.content.Context context,
android.os.Bundle data,
MessageListener listener)
Handle messages from GCM.
|
static boolean |
handleMessage(android.content.Context context,
Map<String,String> data,
MessageListener listener)
Handle messages from FCM.
|
static boolean |
isInsightsEnabled()
Returns if reporting statistics to Insights is enabled.
|
static void |
register(String accessToken,
Voice.RegistrationChannel registrationChannel,
String registrationToken,
RegistrationListener listener)
Register for incoming call messages.
|
static void |
setAudioDevice(AudioDevice audioDevice)
Sets the custom audio device.
|
static void |
setLogLevel(LogLevel level)
Sets the logging level for messages logged by the Voice SDK.
|
static void |
setModuleLogLevel(LogModule module,
LogLevel level)
Sets the logging level for messages logged by a specific module.
|
static void |
setRegion(String region)
Sets the region (Twilio data center) for the SDK.
|
static void |
unregister(String accessToken,
Voice.RegistrationChannel registrationChannel,
String registrationToken,
UnregistrationListener listener)
Unregister from receiving further incoming call messages.
|
public static void register(String accessToken, Voice.RegistrationChannel registrationChannel, String registrationToken, RegistrationListener listener)
RegistrationListener.onRegistered(...)
callback is raised. Once successfully registered,
the registered binding has a time-to-live(TTL) of 1 year. If the registered binding is inactive
for 1 year, it is deleted and push notifications to the registered identity will not succeed.
However, whenever the registered binding is used to reach the registered identity, the TTL is
reset to 1 year.
If registration fails, RegistrationListener.onError(...)
callback is raised with
RegistrationException
. RegistrationException.getMessage(...)
provides the root cause of the failure.
Registration Exception | Error Code | Description |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN | 20101 | Twilio was unable to validate your Access Token |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_HEADER | 20102 | Invalid Access Token header |
VoiceException.EXCEPTION_INVALID_ISSUER_SUBJECT | 20103 | Invalid Access Token issuer or subject |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_EXPIRY | 20104 | Access Token has expired or expiration date is invalid |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_NOT_VALID_YET | 20105 | Access Token not yet valid |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_GRANT | 20106 | Invalid Access Token grants |
VoiceException.EXCEPTION_INVALID_TTL | 20157 | Expiration Time in the Access Token Exceeds Maximum Time Allowed |
VoiceException.EXCEPTION_INVALID_TOKEN | 20403 | Forbidden. The account lacks permission to access the Twilio API |
VoiceException.EXCEPTION_ACCESS_TOKEN_REJECTED | 51007 | Token authentication is rejected by authentication service |
RegistrationException.EXCEPTION_REGISTRATION_ERROR | 31301 | Registration failed. Look at RegistrationException.getMessage(...) for details |
VoiceException.EXCEPTION_BAD_REQUEST | 31400 | Bad Request. The request could not be understood due to malformed syntax |
VoiceException.EXCEPTION_FORBIDDEN | 31403 | Forbidden. The server understood the request, but is refusing to fulfill it |
VoiceException.EXCEPTION_NOT_FOUND | 31404 | Not Found. The server has not found anything matching the request |
VoiceException.EXCEPTION_REQUEST_TIMEOUT | 31408 | Request Timeout. A request timeout occurred |
RegistrationException.EXCEPTION_CONFLICT | 31409 | Conflict. The request could not be processed because of a conflict in the current state of the resource. Another request may be in progress |
RegistrationException.EXCEPTION_UPGRADE_REQUIRED | 31426 | Upgrade Required. The client should switch to a different protocol |
RegistrationException.EXCEPTION_TOO_MANY_REQUEST | 31429 | Too Many Requests. Too many requests were sent in a given amount of time |
VoiceException.EXCEPTION_INTERNAL_SERVER_ERROR | 31500 | Internal Server Error. The server could not fulfill the request due to some unexpected condition |
VoiceException.EXCEPTION_BAD_GATEWAY | 31502 | Bad Gateway. The server is acting as a gateway or proxy, and received an invalid response from a downstream server while attempting to fulfill the request |
VoiceException.EXCEPTION_SERVICE_UNAVAILABLE | 31503 | Service Unavailable. The server is currently unable to handle the request due to a temporary overloading or maintenance of the server |
VoiceException.EXCEPTION_GATEWAY_TIMEOUT | 31504 | Gateway Timeout. The server, while acting as a gateway or proxy, did not receive a timely response from an upstream server |
The identity provided in the accessToken
may only contain alpha-numeric and
underscore characters. Other characters, including spaces, will result in undefined behavior.
Group Name | Event Name | Description | Since version |
registration | registration | Registration is successful | 3.0.0-preview4 |
registration | registration-error | Registration failed | 3.0.0-preview4 |
The maximum number of characters for the identity provided in the token is 121. The identity may only contain alpha-numeric and underscore characters. Other characters, including spaces, or exceeding the maximum number of characters, will result in not being able to place or receive calls.
accessToken
- An access token.registrationChannel
- An enumeration of registration channels.registrationToken
- A GCM or FCM registration token.listener
- A listener that receives registration request status.
final String registrationToken = FirebaseInstanceId.getInstance().getToken(); if (registrationToken != null) { Voice.register(accessToken, Voice.RegistrationChannel.FCM, registrationToken, registrationListener); }
public static void unregister(String accessToken, Voice.RegistrationChannel registrationChannel, String registrationToken, UnregistrationListener listener)
UnregistrationListener.onUnregistered(...)
callback is raised.
If unregistration fails, UnregistrationListener.onError(...)
callback is raised with
RegistrationException
. RegistrationException.getMessage(...)
provides the root cause of the failure.
Registration Exception | Error Code | Description |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN | 20101 | Twilio was unable to validate your Access Token |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_HEADER | 20102 | Invalid Access Token header |
VoiceException.EXCEPTION_INVALID_ISSUER_SUBJECT | 20103 | Invalid Access Token issuer or subject |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_EXPIRY | 20104 | Access Token has expired or expiration date is invalid |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_NOT_VALID_YET | 20105 | Access Token not yet valid |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_GRANT | 20106 | Invalid Access Token grants |
VoiceException.EXCEPTION_INVALID_TTL | 20157 | Expiration Time in the Access Token Exceeds Maximum Time Allowed |
VoiceException.EXCEPTION_INVALID_TOKEN | 20403 | Forbidden. The account lacks permission to access the Twilio API |
VoiceException.EXCEPTION_ACCESS_TOKEN_REJECTED | 51007 | Token authentication is rejected by authentication service |
RegistrationException.EXCEPTION_REGISTRATION_ERROR | 31301 | Registration failed. Look at RegistrationException.getMessage(...) for details |
VoiceException.EXCEPTION_BAD_REQUEST | 31400 | Bad Request. The request could not be understood due to malformed syntax |
VoiceException.EXCEPTION_FORBIDDEN | 31403 | Forbidden. The server understood the request, but is refusing to fulfill it |
VoiceException.EXCEPTION_NOT_FOUND | 31404 | Not Found. The server has not found anything matching the request |
VoiceException.EXCEPTION_REQUEST_TIMEOUT | 31408 | Request Timeout. A request timeout occurred |
RegistrationException.EXCEPTION_CONFLICT | 31409 | Conflict. The request could not be processed because of a conflict in the current state of the resource. Another request may be in progress |
RegistrationException.EXCEPTION_UPGRADE_REQUIRED | 31426 | Upgrade Required. The client should switch to a different protocol |
RegistrationException.EXCEPTION_TOO_MANY_REQUEST | 31429 | Too Many Requests. Too many requests were sent in a given amount of time |
VoiceException.EXCEPTION_INTERNAL_SERVER_ERROR | 31500 | Internal Server Error. The server could not fulfill the request due to some unexpected condition |
VoiceException.EXCEPTION_BAD_GATEWAY | 31502 | Bad Gateway. The server is acting as a gateway or proxy, and received an invalid response from a downstream server while attempting to fulfill the request |
VoiceException.EXCEPTION_SERVICE_UNAVAILABLE | 31503 | Service Unavailable. The server is currently unable to handle the request due to a temporary overloading or maintenance of the server |
VoiceException.EXCEPTION_GATEWAY_TIMEOUT | 31504 | Gateway Timeout. The server, while acting as a gateway or proxy, did not receive a timely response from an upstream server |
The identity provided in the accessToken
may only contain alpha-numeric and
underscore characters. Other characters, including spaces, will result in undefined behavior.
Group Name | Event Name | Description | Since version |
registration | unregistration | Unregistration is successful | 3.0.0-preview4 |
registration | unregistration-error | Unregistration failed | 3.0.0-preview4 |
The maximum number of characters for the identity provided in the token is 121. The identity may only contain alpha-numeric and underscore characters. Other characters, including spaces, or exceeding the maximum number of characters, will result in not being able to place or receive calls.
accessToken
- An access token.registrationChannel
- An enumeration of registration channels.registrationToken
- An FCM or GCM device token.listener
- A listener that receives unregistration request status.
Voice.unregister(accessToken, Voice.RegistrationChannel.FCM, registrationToken, unregistrationListener);
public static Call connect(android.content.Context context, ConnectOptions connectOptions, Call.Listener listener)
Call
. A SecurityException
will be thrown if RECORD_AUDIO
is not granted.
Call.Listener
receives the state of the Call
.
Callback Name | Description | Since version |
Call.Listener.onConnectFailure(Call, CallException) | The call failed to connect. CallException provides details of the root cause. | 3.0.0-preview1 |
Call.Listener.onRinging(Call) | Emitted once before the Call.Listener.onConnected(Call) callback when the callee is being alerted of a Call . | 3.0.0-preview2 |
Call.Listener.onConnected(Call) | The call has connected. | 3.0.0-preview1 |
Call.Listener.onDisconnected(Call, CallException) | The call was disconnected. If the call ends due to an error the `CallException` is non-null. If the call ends normally `CallException` is null. | 3.0.0-preview1 |
If connect
fails, Call.Listener.onConnectFailure(Call, CallException)
callback is raised with CallException
. VoiceException.getMessage()
and VoiceException.getExplanation()
provide details of the failure.
If Call.disconnect()
is called while attempting to connect, the Call.Listener.onDisconnected(Call, CallException)
callback will be raised with no error.
If connect(Context, ConnectOptions, Call.Listener)
fails due to an authentication error, the SDK receives one of the following errors.
Authentication Exception | Error Code | Description |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN | 20101 | Twilio was unable to validate your Access Token |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_HEADER | 20102 | Invalid Access Token header |
VoiceException.EXCEPTION_INVALID_ISSUER_SUBJECT | 20103 | Invalid Access Token issuer or subject |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_EXPIRY | 20104 | Access Token has expired or expiration date is invalid |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_NOT_VALID_YET | 20105 | Access Token not yet valid |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_GRANT | 20106 | Invalid Access Token grants |
VoiceException.EXCEPTION_AUTH_FAILURE | 20151 | Twilio failed to authenticate the client |
VoiceException.EXCEPTION_INVALID_TTL | 20157 | Expiration Time in the Access Token Exceeds Maximum Time Allowed |
VoiceException.EXCEPTION_INVALID_TOKEN | 20403 | Forbidden. The account lacks permission to access the Twilio API |
CallException.EXCEPTION_INVALID_APPLICATION_SID | 21218 | Invalid ApplicationSid |
If connect(Context, ConnectOptions, Call.Listener)
fails due to any other reasons, the SDK receives one of the following errors.
Insights :
Group Name | Event Name | Description | Since version |
connection | outgoing | Outgoing call is made. Call state is in Call.State.CONNECTING state | 3.0.0-beta2 |
settings | codec | Negotiated selected codec is received and remote SDP is set | 5.0.1 |
If connect fails, an error event is published to Insights.
Group Name | Event Name | Description | Since version |
connection | error | Error description. Call state transitions to Call.State.DISCONNECTED | 3.0.0-beta2 |
context
- An Android context.connectOptions
- A set of options that allow you to configure your Call
.listener
- A listener that receives call status.Call
ConnectOptions connectOptions = new ConnectOptions.Builder(accessToken).build();
Call call = Voice.connect(context, connectOptions, new Call.Listener() {
@Override
public void onRinging(@NonNull Call call) {
Log.d(TAG, "Ringing");
}
@Override
public void onConnected(@NonNull final Call call) {
Log.d(TAG, "Received onConnected " + call.getSid());
}
@Override
public void onConnectFailure(@NonNull Call call, @NonNull CallException callException) {
Log.d(TAG, "Received onConnectFailure with CallException: " + callException.getErrorCode()+ ":" + callException.getMessage());
}
@Override
public void onDisconnected(@NonNull Call call, CallException callException) {
if (callException != null) {
Log.d(TAG, "Received onDisconnected with CallException: " + callException.getMessage() + ": " + call.getSid());
} else {
Log.d(TAG, "Received onDisconnected");
}
}
});
}
public static Call connect(android.content.Context context, String accessToken, Call.Listener listener)
Call
. A SecurityException
will be thrown if RECORD_AUDIO
is not granted.
Call.Listener
receives the state of the Call
.
Callback Name | Description | Since version |
Call.Listener.onConnectFailure(Call, CallException) | The call failed to connect. CallException provides details of the root cause. | 3.0.0-preview1 |
Call.Listener.onRinging(Call) | Emitted once before the Call.Listener.onConnected(Call) callback when the callee is being alerted of a Call . | 3.0.0-preview2 |
Call.Listener.onConnected(Call) | The call has connected. | 3.0.0-preview1 |
Call.Listener.onDisconnected(Call, CallException) | The call was disconnected. If the call ends due to an error the `CallException` is non-null. If the call ends normally `CallException` is null. | 3.0.0-preview1 |
If connect
fails, Call.Listener.onConnectFailure(Call, CallException)
callback is raised with CallException
. VoiceException.getMessage()
and VoiceException.getExplanation()
provide details of the failure.
If Call.disconnect()
is called while attempting to connect, the Call.Listener.onDisconnected(Call, CallException)
callback will be raised with no error.
If connect(Context, String, Call.Listener)
fails due to an authentication error, the SDK receives one of the following errors.
Authentication Exception | Error Code | Description |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN | 20101 | Twilio was unable to validate your Access Token |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_HEADER | 20102 | Invalid Access Token header |
VoiceException.EXCEPTION_INVALID_ISSUER_SUBJECT | 20103 | Invalid Access Token issuer or subject |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_EXPIRY | 20104 | Access Token has expired or expiration date is invalid |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_NOT_VALID_YET | 20105 | Access Token not yet valid |
VoiceException.EXCEPTION_INVALID_ACCESS_TOKEN_GRANT | 20106 | Invalid Access Token grants |
VoiceException.EXCEPTION_AUTH_FAILURE | 20151 | Twilio failed to authenticate the client |
VoiceException.EXCEPTION_INVALID_TTL | 20157 | Expiration Time in the Access Token Exceeds Maximum Time Allowed |
VoiceException.EXCEPTION_INVALID_TOKEN | 20403 | Forbidden. The account lacks permission to access the Twilio API |
CallException.EXCEPTION_INVALID_APPLICATION_SID | 21218 | Invalid ApplicationSid |
If connect(Context, String, Call.Listener)
fails due to any other reason, the SDK receives one of the following errors.
The identity provided in the accessToken
may only contain alpha-numeric and
underscore characters. Other characters, including spaces, will result in undefined behavior.
Insights :
Group Name | Event Name | Description | Since version |
connection | outgoing | Outgoing call is made. Call state is in Call.State.CONNECTING state | 3.0.0-beta2 |
settings | codec | Negotiated selected codec is received and remote SDP is set | 5.0.1 |
If connect fails, an error event is published to Insights.
Group Name | Event Name | Description | Since version |
connection | error | Error description. Call state transitions to Call.State.DISCONNECTED | 3.0.0-beta2 |
The maximum number of characters for the identity provided in the token is 121. The identity may only contain alpha-numeric and underscore characters. Other characters, including spaces, or exceeding the maximum number of characters, will result in not being able to place or receive calls.
context
- An Android context.accessToken
- The accessToken that provides the identity and grants of the caller.listener
- A listener that receives call status.Call
Call call = Voice.connect(context, accessToken, new Call.Listener() {
@Override
public void onRinging(@NonNull Call call) {
Log.d(TAG, "Ringing");
}
@Override
public void onConnected(@NonNull final Call call) {
Log.d(TAG, "Received onConnected " + call.getSid());
}
@Override
public void onConnectFailure(@NonNull Call call, @NonNull CallException callException) {
Log.d(TAG, "Received onConnectFailure with CallException: " + callException.getErrorCode()+ ":" + callException.getMessage());
}
@Override
public void onDisconnected(@NonNull Call call, CallException callException) {
if (callException != null) {
Log.d(TAG, "Received onDisconnected with CallException: " + callException.getMessage() + ": " + call.getSid());
} else {
Log.d(TAG, "Received onDisconnected");
}
}
});
}
public static boolean handleMessage(android.content.Context context, Map<String,String> data, MessageListener listener)
Twilio sends call
notification messages via GCM/FCM.
The message type is encoded in the dictionary with the key twi_message_type
with the value twilio.voice.call
.
A call
message is sent when someone wants to reach the registered identity
.
Passing a call
message into handleMessage(Context, Bundle, MessageListener)
will result in a CallInvite
raised in the MessageListener
and return true
.
A CancelledCallInvite
will be raised to the provided MessageListener
for
the following reasons:
Passing malformed data to handleMessage(Context, Map, MessageListener)
will return false
and no MessageListener
callback will be raised.
Insights :
Group Name | Event Name | Description | Since version |
connection | incoming | Incoming call notification received | 3.0.0-preview1 |
connection | listen | Raised when an attempt to listen for cancellations is made | 5.0.0 |
connection | listening | Raised when an attempt to listen for cancellations has succeeded | 5.0.0 |
connection | cancel | Raised when a cancellation has been reported | 5.0.0 |
connection | listening-error | Raised when an attempt to listen for cancellation has failed | 5.0.0 |
registration | unsupported-cancel-message-error | Raised when a "cancel" push notification is processed by the SDK. This version of the SDK does not support "cancel" push notifications | 5.0.0 |
context
- An Android context.data
- Push notification payload.listener
- A MessageListener
to receive incoming push notification callbacks.
boolean valid = Voice.handleMessage(dataMap, new MessageListener() {
@Override
public void onCallInvite(@NonNull CallInvite callInvite) {
Log.d(TAG, "Received CallInvite");
}
@Override
public void onCancelledCallInvite(@NonNull CancelledCallInvite cancelledCallInvite) {
Log.d(TAG, "Received CancelledCallInvite");
}
});
public static boolean handleMessage(android.content.Context context, android.os.Bundle data, MessageListener listener)
Twilio sends call
notification messages via GCM/FCM.
The message type is encoded in the dictionary with the key twi_message_type
with the value twilio.voice.call
.
A call
message is sent when someone wants to reach the registered identity
.
Passing a call
message into handleMessage(Context, Bundle, MessageListener)
will result in a CallInvite
raised in the MessageListener
and return true
.
A CancelledCallInvite
will be raised to the provided MessageListener
for
the following reasons:
Passing malformed data to handleMessage(Context, Map, MessageListener)
will return false
and no MessageListener
callback will be raised.
Insights :
Group Name | Event Name | Description | Since version |
connection | incoming | Incoming call notification received | 3.0.0-preview1 | connection | listen | Raised when an attempt to listen for cancellations is made | 5.0.0 |
connection | listening | Raised when an attempt to listen for cancellations has succeeded | 5.0.0 |
connection | cancel | Raised when a cancellation has been reported | 5.0.0 |
connection | listening-error | Raised when an attempt to listen for cancellation has failed | 5.0.0 |
registration | unsupported-cancel-message-error | Raised when a "cancel" push notification is processed by the SDK. This version of the SDK does not support "cancel" push notifications | 5.0.0 |
context
- An Android context.data
- Push notification payload.listener
- A MessageListener
to receive incoming push notification callbacks.
boolean valid = Voice.handleMessage(dataMap, new MessageListener() {
@Override
public void onCallInvite(@NonNull CallInvite callInvite) {
Log.d(TAG, "Received CallInvite");
}
@Override
public void onCancelledCallInvite(@NonNull CancelledCallInvite cancelledCallInvite) {
Log.d(TAG, "Received CancelledCallInvite");
}
});
public static String getVersion()
public static LogLevel getLogLevel()
LogLevel.ERROR
.public static LogLevel getModuleLogLevel(LogModule module)
LogLevel.ERROR
.public static boolean isInsightsEnabled()
enableInsights
and can be
updated via enableInsights(boolean)
public static String getRegion()
region
. The default region uses Global Low Latency
routing, which establishes a connection with the closest region to the user. This value can
be updated via setRegion(String)
public static AudioDevice getAudioDevice()
public static void setLogLevel(LogLevel level)
level
- The logging levelpublic static void setModuleLogLevel(LogModule module, LogLevel level)
module
- The module for this log level.level
- The logging level.public static void enableInsights(boolean enable)
NOTE: Setting the flag during a call will not be applied to ongoing calls. The flag will be
applied to subsequent connect(Context, String, Call.Listener)
or
handleMessage(Context, Bundle, MessageListener)
API calls.
public static void setRegion(String region)
NOTE: Setting the region during a call will not be applied to ongoing calls. The region will
be applied to subsequent connect(Context, String, Call.Listener)
or
handleMessage(Context, Bundle, MessageListener)
API calls.
region
- The region.public static void setAudioDevice(AudioDevice audioDevice) throws UnsupportedOperationException
audioDevice
can be updated when there is no
call in progress and will be applied to subsequent connect(Context, String, Call.Listener)
or handleMessage(Context, Bundle,MessageListener)
API calls. Setting the
audioDevice
during a call will result in UnsupportedOperationException
.audioDevice
- The audio device.UnsupportedOperationException
5.2.0