Interface Options

Options that may be passed to the Device constructor, or Device.setup via public API


  • Options



Optional RTCPeerConnection

RTCPeerConnection: any

Overrides the native RTCPeerConnection class.

By default, the SDK will use the unified-plan SDP format if the browser supports it. Unexpected behavior may happen if the RTCPeerConnection parameter uses an SDP format that is different than what the SDK uses.

For example, if the browser supports unified-plan and the RTCPeerConnection parameter uses plan-b by default, the SDK will use unified-plan which will cause conflicts with the usage of the RTCPeerConnection.

In order to avoid this issue, you need to explicitly set the SDP format that you want the SDK to use with the RTCPeerConnection via Device.ConnectOptions.rtcConfiguration for outgoing calls. Or Call.AcceptOptions.rtcConfiguration for incoming calls.

See the example below. Assuming the RTCPeerConnection you provided uses plan-b by default, the following code sets the SDP format to unified-plan instead.

// Outgoing calls
const call = await device.connect({
  rtcConfiguration: {
    sdpSemantics: 'unified-plan'
  // Other options

// Incoming calls
device.on('incoming', call => {
    rtcConfiguration: {
      sdpSemantics: 'unified-plan'
    // Other options

Optional allowIncomingWhileBusy

allowIncomingWhileBusy: undefined | false | true

Whether the Device should raise the incomingEvent event when a new call invite is received while already on an active call. Default behavior is false.

Optional appName

appName: undefined | string

A name for the application that is instantiating the Device. This is used to improve logging in Insights by associating Insights data with a specific application, particularly in the case where one account may be connected to by multiple applications.

Optional appVersion

appVersion: undefined | string

A version for the application that is instantiating the Device. This is used to improve logging in Insights by associating Insights data with a specific version of the given application. This can help track down when application-level bugs were introduced.

Optional closeProtection

closeProtection: boolean | string

Whether to enable close protection, to prevent users from accidentally navigating away from the page during a call. If string, the value will be used as a custom message.

Optional codecPreferences

codecPreferences: Codec[]

An ordered array of codec names, from most to least preferred.

Optional disableAudioContextSounds

disableAudioContextSounds: undefined | false | true

Whether AudioContext sounds should be disabled. Useful for trouble shooting sound issues that may be caused by AudioContext-specific sounds. If set to true, will fall back to HTMLAudioElement sounds.

Optional dscp

dscp: undefined | false | true

Whether to use googDscp in RTC constraints.

Optional edge

edge: string[] | string

The edge value corresponds to the geographic location that the client will use to connect to Twilio infrastructure. The default value is "roaming" which automatically selects an edge based on the latency of the client relative to available edges.

Optional enableImprovedSignalingErrorPrecision

enableImprovedSignalingErrorPrecision: undefined | false | true

Enhance the precision of errors emitted by Device and Call objects.

The default value of this option is false.

When this flag is enabled, some errors that would have been described with a generic error code, namely 53000 and 31005, are now described with a more precise error code. With this feature, the following errors now have their own error codes. Please see this page for more details about each error.

  • Device Error Changes
const device = new Device(token, {
  enableImprovedSignalingErrorPrecision: true,
device.on('error', (deviceError) => {
  // the following table describes how deviceError will change with this feature flag
Device Error Name Device Error Code with Feature Flag Enabled Device Error Code with Feature Flag Disabled
GeneralErrors.ApplicationNotFoundError 31001 53000
GeneralErrors.ConnectionDeclinedError 31002 53000
GeneralErrors.ConnectionTimeoutError 31003 53000
MalformedRequestErrors.MissingParameterArrayError 31101 53000
MalformedRequestErrors.AuthorizationTokenMissingError 31102 53000
MalformedRequestErrors.MaxParameterLengthExceededError 31103 53000
MalformedRequestErrors.InvalidBridgeTokenError 31104 53000
MalformedRequestErrors.InvalidClientNameError 31105 53000
MalformedRequestErrors.ReconnectParameterInvalidError 31107 53000
SignatureValidationErrors.AccessTokenSignatureValidationFailed 31202 53000
AuthorizationErrors.NoValidAccountError 31203 53000
AuthorizationErrors.JWTTokenExpirationTooLongError 31207 53000
ClientErrors.NotFound 31404 53000
ClientErrors.TemporarilyUnavilable 31480 53000
ClientErrors.BusyHere 31486 53000
SIPServerErrors.Decline 31603 53000
  • Call Error Changes
const device = new Device(token, {
  enableImprovedSignalingErrorPrecision: true,
const call = device.connect(...);
call.on('error', (callError) => {
  // the following table describes how callError will change with this feature flag
Call Error Name Call Error Code with Feature Flag Enabled Call Error Code with Feature Flag Disabled
GeneralErrors.ConnectionDeclinedError 31002 31005
AuthorizationErrors.InvalidJWTTokenError 31204 31005
AuthorizationErrors.JWTTokenExpiredError 31205 31005

Optional enumerateDevices

enumerateDevices: any

Overrides the native MediaDevices.enumerateDevices API.

Optional forceAggressiveIceNomination

forceAggressiveIceNomination: undefined | false | true

Experimental feature. Whether to use ICE Aggressive nomination.

Optional getUserMedia

getUserMedia: any

Overrides the native MediaDevices.getUserMedia API.

Optional logLevel

logLevel: LogLevelDesc

Sets the log level.

Possible values include any of the following numbers:
0 = trace, 1 = debug, 2 = info, 3 = warn, 4 = error, 5 = silent

Or any of the following strings:
'trace', 'debug', 'info', 'warn', 'error', 'silent'

Optional maxAverageBitrate

maxAverageBitrate: undefined | number

The maximum average audio bitrate to use, in bits per second (bps) based on RFC-7587 7.1. By default, the setting is not used. If you specify 0, then the setting is not used. Any positive integer is allowed, but values outside the range 6000 to 510000 are ignored and treated as 0. The recommended bitrate for speech is between 8000 and 40000 bps as noted in RFC-7587 3.1.1.

Optional maxCallSignalingTimeoutMs

maxCallSignalingTimeoutMs: undefined | number

The maximum duration to attempt to reconnect to a preferred URI. This is used by signaling reconnection in that during the existence of any call, edge-fallback is disabled until this length of time has elapsed.

Using a value of 30000 as an example: while a call exists, the Device will attempt to reconnect to the edge that the call was established on for approximately 30 seconds. After the next failure to connect, the Device will use edge-fallback.

This feature is opt-in, and will not work until a number greater than 0 is explicitly specified within the Device options.

Optional sounds

sounds: Partial<Record<SoundName, string>>

A mapping of custom sound URLs by sound name.

Optional tokenRefreshMs

tokenRefreshMs: undefined | number

Number of milliseconds fewer than the token's TTL to emit the tokenWillExpire event. Default is 10000 (10 seconds).

Generated using TypeDoc