Package com.twilio.voice

Class CallInvite

java.lang.Object

com.twilio.voice.CallInvite

All Implemented Interfaces:

android.os.Parcelable

public class CallInvite
extends Object
implements android.os.Parcelable

Represents an incoming call message from Twilio. This object is used to respond to an incoming call by calling accept(Context, Call.Listener) or reject(Context)

Nested Class Summary

Nested classes/interfaces inherited from interface android.os.Parcelable

android.os.Parcelable.ClassLoaderCreator<T extends Object>, android.os.Parcelable.Creator<T extends Object>

Field Summary

Fields

Modifier and Type	Field	Description
static final android.os.Parcelable.Creator	CREATOR

Fields inherited from interface android.os.Parcelable

CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE

Method Summary

Modifier and Type	Method	Description
Call	accept(android.content.Context context, AcceptOptions acceptOptions, Call.Listener listener)	Accepts the CallInvite with the provided AcceptOptions and returns a new Call.
Call	accept(android.content.Context context, Call.Listener listener)	Accepts the CallInvite with default AcceptOptions and returns a new Call.
int	describeContents()
boolean	equals(Object o)
CallerInfo	getCallerInfo()	Returns the CallerInfo that provides caller verification information about the caller.
String	getCallSid()	Returns the CallSid.
Map<String,String>	getCustomParameters()	Returns the custom parameters.
String	getFrom()	Returns the caller information when available.
String	getTo()	Returns the callee information.
static boolean	isValid(android.content.Context context, android.os.Bundle data)	Validates whether the payload is a valid notification sent by Twilio.
static boolean	isValid(android.content.Context context, Map<String,String> data)	Validates whether the payload is a valid notification sent by Twilio.
void	reject(android.content.Context context)	Rejects the incoming CallInvite.
String	sendMessage(CallMessage message)	Sends a user-defined message to endpoints that have subscribed for user-defined messages.
void	writeToParcel(android.os.Parcel dest, int flags)

Methods inherited from class java.lang.Object

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

Field Details

CREATOR

public static final android.os.Parcelable.Creator CREATOR

Method Details

getFrom

@Nullable
public String getFrom()

Returns the caller information when available.

getTo

@NonNull
public String getTo()

Returns the callee information.

getCallSid

@NonNull
public String getCallSid()

Returns the CallSid.

getCallerInfo

@NonNull
public CallerInfo getCallerInfo()

Returns the CallerInfo that provides caller verification information about the caller.

getCustomParameters

@NonNull
public Map<String,String> getCustomParameters()

Returns the custom parameters.

 // Pass custom parameters in TwiML
 <?xml version="1.0" encoding="UTF-8"?>
 <Response>
    <Dial answerOnBridge="false" callerId="client:alice">
        <Client>
            <Identity>bob</Identity>
            <Parameter name="caller_first_name" value="alice"  />
            <Parameter name="caller_last_name" value="smith"  />
        </Client>
     </Dial>
 </Response>
 
 `callInvite.getCustomParameters()` returns a map of key-value pair passed in the TwiML.
 
 "caller_first_name" -> "alice"
 "caller_last_name" -> "smith"
 

NOTE: While the value field passed into <Parameter> gets URI encoded by the Twilio infrastructure and URI decoded when parsed during the creation of a CallInvite, the name does not get URI encoded or decoded. As a result, it is recommended that the name field only use ASCII characters.

accept

@NonNull
public Call accept(@NonNull
 android.content.Context context,
 @NonNull
 AcceptOptions acceptOptions,
 @NonNull
 Call.Listener listener)

Accepts the CallInvite with the provided AcceptOptions and returns a new Call. A SecurityException will be thrown if RECORD_AUDIO is not granted.

Call.Listener receives the state of the Call.

Call.Listener events

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)	This callback should not be invoked when calling accept(Context, AcceptOptions, Call.Listener)	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 accept 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 accept, the Call.Listener.onDisconnected(Call, CallException) callback will be raised with no error.

If accept(Context, AcceptOptions, Call.Listener) fails due to an authentication error, the SDK receives the following error.

Authentication Exceptions

Authentication Exception	Error Code	Description
VoiceException.EXCEPTION_AUTH_FAILURE	20151	Twilio failed to authenticate the client

If accept(Context, AcceptOptions, Call.Listener) fails due to any other reason, the SDK receives one of the following errors.

Call Exceptions

Call Exception	Error Code	Description
CallException.EXCEPTION_CONNECTION_ERROR	31005	Connection error
CallException.EXCEPTION_CALL_CANCELLED	31008	Call Cancelled
CallException.EXCEPTION_TRANSPORT_ERROR	31009	Transport error
CallException.EXCEPTION_MALFORMED_REQUEST	31100	Malformed request
CallException.EXCEPTION_AUTHORIZATION_ERROR	31201	Authorization error
VoiceException.EXCEPTION_BAD_REQUEST	31400	Bad Request
VoiceException.EXCEPTION_FORBIDDEN	31403	Forbidden
VoiceException.EXCEPTION_NOT_FOUND	31404	Not Found
VoiceException.EXCEPTION_REQUEST_TIMEOUT	31408	Request Timeout
CallException.EXCEPTION_TEMPORARILY_UNAVAILABLE_ERROR	31480	Temporarily Unavailable
CallException.EXCEPTION_CALL_OR_TRANSACTION_DOES_NOT_EXIST_ERROR	31481	Call/Transaction Does Not Exist
CallException.EXCEPTION_BUSY_HERE_ERROR	31486	Busy Here
CallException.EXCEPTION_REQUEST_TERMINATED_ERROR	31487	Request Terminated
VoiceException.EXCEPTION_INTERNAL_SERVER_ERROR	31500	Internal Server Error
VoiceException.EXCEPTION_BAD_GATEWAY	31502	Bad Gateway
VoiceException.EXCEPTION_SERVICE_UNAVAILABLE	31503	Service Unavailable
VoiceException.EXCEPTION_GATEWAY_TIMEOUT	31504	Gateway Timeout
CallException.EXCEPTION_DNS_RESOLUTION	31530	DNS Resolution Error
CallException.EXCEPTION_BUSY_EVERYWHERE_ERROR	31600	Busy Everywhere
CallException.EXCEPTION_DECLINE_ERROR	31603	Decline
CallException.EXCEPTION_DOES_NOT_EXIST_ANYWHERE_ERROR	31604	Does Not Exist Anywhere
CallException.EXCEPTION_SIGNALING_CONNECTION_DISCONNECTED	53001	Signaling connection disconnected
CallException.EXCEPTION_CLIENT_LOCAL_MEDIA_DESCRIPTION	53400	Client is unable to create or apply a local media description
CallException.EXCEPTION_SERVER_LOCAL_MEDIA_DESCRIPTION	53401	Server is unable to create or apply a local media description
CallException.EXCEPTION_CLIENT_REMOTE_MEDIA_DESCRIPTION	53402	Client is unable to apply a remote media description
CallException.EXCEPTION_SERVER_REMOTE_MEDIA_DESCRIPTION	53403	Server is unable to apply a remote media description
CallException.EXCEPTION_NO_SUPPORTED_CODEC	53404	No supported code
CallException.EXCEPTION_MEDIA_CONNECTION_FAILED	53405	Media connection failed
CallException.EXCEPTION_MEDIA_DTLS_TRANSPORT_FAILED	53407	The media connection failed due to DTLS handshake failure

Insights :

Insights events

Group Name	Event Name	Description	Since version
connection	accepted-by-local	Call state remains Call.State.CONNECTING	3.0.0-beta2
settings	codec	Negotiated selected codec is received and remote SDP is set	5.0.1

If accept fails, an error event is published to Insights.

Insights events

Group Name	Event Name	Description	Since version
connection	error	Error description. Call state transitions to Call.State.DISCONNECTED	3.0.0-beta2

Parameters:

context - An Android context.

acceptOptions - The options that configure the accepted call.

listener - A listener that receives call status.

Returns:

A new Call

Usage example:

 IceOptions iceOptions = new IceOptions.Builder()
         .iceTransportPolicy(IceTransportPolicy.RELAY)
         .build();
 AcceptOptions acceptOptions = new AcceptOptions.Builder()
         .iceOptions(iceOptions)
         .build();
 Call call = callInvite.accept(context, acceptOptions, new Call.Listener() {
     @Override
      public void onRinging(@NonNull Call call) {
          // This callback will not be invoked when accepting a call invite
      }

     @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");
          }
      }
  });
  }
 

accept

@NonNull
public Call accept(@NonNull
 android.content.Context context,
 @NonNull
 Call.Listener listener)

Accepts the CallInvite with default AcceptOptions and returns a new Call. A SecurityException will be thrown if RECORD_AUDIO is not granted.

Call.Listener receives the state of the Call.

Call.Listener events

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)	This callback should not be invoked when calling accept(Context, Call.Listener)	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 accept 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 accept, the Call.Listener.onDisconnected(Call, CallException) callback will be raised with no error.

If accept(Context, Call.Listener) fails due to an authentication error, the SDK receives the following error.

Authentication Exceptions

Authentication Exception	Error Code	Description
VoiceException.EXCEPTION_AUTH_FAILURE	20151	Twilio failed to authenticate the client

If accept(Context, Call.Listener) fails due to any other reason, the SDK receives one of the following errors.

Call Exceptions

Call Exception	Error Code	Description
CallException.EXCEPTION_CONNECTION_ERROR	31005	Connection error
CallException.EXCEPTION_CALL_CANCELLED	31008	Call Cancelled
CallException.EXCEPTION_TRANSPORT_ERROR	31009	Transport error
CallException.EXCEPTION_MALFORMED_REQUEST	31100	Malformed request
CallException.EXCEPTION_AUTHORIZATION_ERROR	31201	Authorization error
VoiceException.EXCEPTION_BAD_REQUEST	31400	Bad Request
VoiceException.EXCEPTION_FORBIDDEN	31403	Forbidden
VoiceException.EXCEPTION_NOT_FOUND	31404	Not Found
VoiceException.EXCEPTION_REQUEST_TIMEOUT	31408	Request Timeout
CallException.EXCEPTION_TEMPORARILY_UNAVAILABLE_ERROR	31480	Temporarily Unavailable
CallException.EXCEPTION_CALL_OR_TRANSACTION_DOES_NOT_EXIST_ERROR	31481	Call/Transaction Does Not Exist
CallException.EXCEPTION_BUSY_HERE_ERROR	31486	Busy Here
CallException.EXCEPTION_REQUEST_TERMINATED_ERROR	31487	Request Terminated
VoiceException.EXCEPTION_INTERNAL_SERVER_ERROR	31500	Internal Server Error
VoiceException.EXCEPTION_BAD_GATEWAY	31502	Bad Gateway
VoiceException.EXCEPTION_SERVICE_UNAVAILABLE	31503	Service Unavailable
VoiceException.EXCEPTION_GATEWAY_TIMEOUT	31504	Gateway Timeout
CallException.EXCEPTION_DNS_RESOLUTION	31530	DNS Resolution Error
CallException.EXCEPTION_BUSY_EVERYWHERE_ERROR	31600	Busy Everywhere
CallException.EXCEPTION_DECLINE_ERROR	31603	Decline
CallException.EXCEPTION_DOES_NOT_EXIST_ANYWHERE_ERROR	31604	Does Not Exist Anywhere
CallException.EXCEPTION_SIGNALING_CONNECTION_DISCONNECTED	53001	Signaling connection disconnected
CallException.EXCEPTION_CLIENT_LOCAL_MEDIA_DESCRIPTION	53400	Client is unable to create or apply a local media description
CallException.EXCEPTION_SERVER_LOCAL_MEDIA_DESCRIPTION	53401	Server is unable to create or apply a local media description
CallException.EXCEPTION_CLIENT_REMOTE_MEDIA_DESCRIPTION	53402	Client is unable to apply a remote media description
CallException.EXCEPTION_SERVER_REMOTE_MEDIA_DESCRIPTION	53403	Server is unable to apply a remote media description
CallException.EXCEPTION_NO_SUPPORTED_CODEC	53404	No supported code
CallException.EXCEPTION_MEDIA_CONNECTION_FAILED	53405	Media connection failed
CallException.EXCEPTION_MEDIA_DTLS_TRANSPORT_FAILED	53407	The media connection failed due to DTLS handshake failure

Insights :

Insights events

Group Name	Event Name	Description	Since version
connection	accepted-by-local	Call state remains Call.State.CONNECTING	3.0.0-beta2
settings	codec	Negotiated selected codec is received and remote SDP is set	5.0.1

If accept fails, an error event is published to Insights.

Insights events

Group Name	Event Name	Description	Since version
connection	error	Error description. Call state transitions to Call.State.DISCONNECTED	3.0.0-beta2

Parameters:

context - An Android context.

listener - A listener that receives call status.

Returns:

A new Call

Usage example:

 Call call = callInvite.accept(context, new Call.Listener() {
     @Override
      public void onRinging(@NonNull Call call) {
          // This callback will not be invoked when accepting a call invite
      }

     @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");
          }
      }
  });
  }
 

reject

public void reject(@NonNull
 android.content.Context context)

Rejects the incoming CallInvite.

Insights :

Insights events

Group Name	Event Name	Description	Since version
connection	rejected-by-local	Call invite is rejected	3.0.0-beta2
connection	error	The event will be sent with code 31600 and message "Busy Everywhere : SIP/2.0 600 Call Rejected"	3.1.0

describeContents

public int describeContents()

Specified by:

describeContents in interface android.os.Parcelable

writeToParcel

public void writeToParcel(android.os.Parcel dest,
 int flags)

Specified by:

writeToParcel in interface android.os.Parcelable

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 either a callback argument to the Voice.handleMessage(Context, Map, MessageListener) method and/or as an accept option when a call invite is either accepted or rejected. 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, String, VoiceException) callback. When attempting to send a message larger than 10k, the error will not show in the developer console. A call message with content that does not match the content type will not result in the Call.CallMessageListener.onMessageFailure(String, String, VoiceException) callback but will generate an error in your Twilio developer console. For example, a call message with content type "application/json" but with the content "Hello World", which is not a valid JSON object, will result in such error.

Parameters:

message - The call message to send.

Returns:

An unique identifier for tracking the message.

isValid

public static boolean isValid(android.content.Context context,
 android.os.Bundle data)

Validates whether the payload is a valid notification sent by Twilio. A valid notification payload will result in a CallInvite being raised via MessageListener.onCallInvite(CallInvite) callback when passed to Voice.handleMessage(...).

Parameters:

context - An Android context.

data - Push notification payload.

Returns:

A boolean value that indicates whether the payload is a valid notification sent by Twilio.

isValid

public static boolean isValid(android.content.Context context,
 Map<String,String> data)

Validates whether the payload is a valid notification sent by Twilio. A valid notification payload will result in a CallInvite being raised via MessageListener.onCallInvite(CallInvite) callback when passed to Voice.handleMessage(...).

Parameters:

context - An Android context.

data - Push notification payload.

Returns:

A boolean value that indicates whether the payload is a valid notification sent by Twilio.

equals

public boolean equals(Object o)

Overrides:

equals in class Object