You're viewing the documentation for the 2.X version of the Voice JavaScript SDK. View the Migration Guide to learn how to migrate from 1.X to 2.X or view the 1.x-specific documentation.
The Twilio Client JavaScript SDK has been renamed to Twilio Voice JavaScript SDK.
The Device
object is available when the JavaScript SDK is included in your application. It represents a softphone that communicates with Twilio to facilitate inbound and outbound audio connections.
For the full API reference, view the autogenerated documentation on GitHub.
Throughout this page, you will see device
with a lowercase "d" and Device
with an uppercase "D".
Device
refers to the Device
object provided by the SDK.
device
represents an instance of a Device
, created with the new
keyword:
const device = new Device(token);
A new instance of a Device
should be constructed by using the new
keyword and passing an Access Token as the first argument. The constructor also takes an optional second argument, DeviceOptions
.
No signaling channel will be opened when instantiating a new Device
. The signaling WebSocket will be opened when either device.register()
or device.connect()
are called.
The maximum number of characters for the identity
provided in the Access 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.
const device = new Device(token);
The DeviceOptions
parameter is optional. The Device
instance's options can be updated after instantiation using the device.updateOptions()
method.
Examples of using DeviceOptions
to specify an Edge location:
1// Instantiate the device with a specified edge location2const device = new Device(token, { edge: 'ashburn'});34// Instantiate the device with a specified edge and auto-fallback functionality5const device = new Device(token, { edge: ['ashburn', 'sydney'] });
To see all of the possible properties, see the DeviceOptions section below.
The Device
instance can be configured using the DeviceOptions
parameter in two ways: during instantiation with the new
keyword or by calling device.updateOptions()
.
1const deviceOptions = {2edge: 'ashburn',3}45// pass the options object as the second argument in Device constructor6const device = new Device(token, deviceOptions);78// or910// use the updateOptions method after instantiating the device11const device = new Device(token);12device.updateOptions(deviceOptions);
DeviceOptions
is a JavaScript object with the properties listed in the table below. All properties are optional.
Options Property | Description |
---|---|
allowIncomingWhileBusy Boolean default: false | Whether the Device instance should raise the 'incoming' event when a new call invite is received while already on an active call. |
appName string | A name for the application that is instantiating the Device instance. This is used to improve logging in Insights. |
appVersion string | A version for the application that is instantiating the Device instance. This is used to improve logging in Insights. |
closeProtection Boolean or string default: false | Setting this property to true will enable a dialog prompt with the text "A call is currently in progress. Leaving or reloading the page will end the call." when closing a page which has an active connection. Setting the property to a string will create a custom message prompt with that string . If custom text is not supported by the browser, Twilio will display the browser's default dialog. |
codecPreferences string[] default: ["pcmu", "opus"] | An array of codec names ordered from most-preferred to least-preferred. Opus and PCMU are the two codecs currently supported by Twilio Voice JS SDK. Opus can provide better quality for lower bandwidth, particularly noticeable in poor network conditions. Examples: ["opus", "pcmu"] , ["pcmu"] |
disableAudioContextSounds Boolean | Whether AudioContext sounds should be disabled. Useful for troubleshooting sound issues that may be caused by AudioContext-specific sounds. If set to true , the Device instance will fall back to HTMLAudioElement sounds. |
dscp Boolean | Whether to use googDscp in RTC constraints |
edge string[] or string default: "roaming" | The Edge location to connect to. If using an array of edges, sort by highest priority to lowest priority. The array will be used to provide auto fallback functionality. Check the Device instance's current edge using the device.edge read-only property. If the Device instance is offline, the edge will be null . See the Edges documentation for more details. |
enableImprovedSignalingErrorPrecision Boolean default: false | When set to true , some errors that would have been described with a generic error code are now described with a more precise error code. Please see this section for more details. |
enumerateDevices function | Pass a custom enumerateDevices function to override what Twilio uses when requesting a list of available media input and output devices. |
forceAggressiveIceNomination Boolean default: false | Experimental feature. Sets whether the Device instance should use ICE Aggressive nomination. If your deployment is on devices with one network interface and your Round Trip Time (RTT) to Twilio's Servers is typically greater than 96 milliseconds, this feature may help reduce call connect time. As this is an experimental feature, we don't recommend enabling this until after testing it thoroughly in your deployment. |
getUserMedia function | Pass a custom getUserMedia function to override what Twilio uses to create an input MediaStream. |
logLevel number or string | The Voice JavaScript SDK exposes a loglevel-based logger to allow for runtime logging configuration. 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' 'TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'SILENT' See the loglevel docs for more information. |
maxAverageBitrate number | Max average bitrate to better control how much bandwidth your VoIP application should use. See RFC-7587 section 7.1. Only applicable when using Opus codec. By default, the Opus codec is set up with a transmission rate of around 32 kbps (40-50kbps on the wire). Max Average Bitrate can be set to as low as 6000 bps and as high as 510000 bps. Values outside this range are ignored and the default Opus operation mode is used. Lowering the max average bitrate impacts audio quality. The recommended bitrate for speech is between 8000 and 40000 bps. If you set maxAverageBitrate to 0 , the setting is not used. |
maxCallSignalingTimeoutMs number default: 0 | The maximum duration in milliseconds the Twilio.Device will attempt to reconnect to the most-recently-used edge in the event of a signaling connectivity loss. After the provided time has passed during reconnection attempts, the Twilio.Device will then use edge fallback. The default value of 0 means that signaling reconnection may not occur, since a change of edge during a reconnection attempt will cause a Call to fail. Since the Twilio.Device will only attempt to reestablish connectivity for up to 30 seconds, the maximum value you would want to use here is 30000 milliseconds. Read more about edge fallback and signaling reconnection on the Edge Locations page. Note: Setting this option to a value greater than zero means Twilio will not terminate the call until the timeout has expired. Please take this into consideration if your application contains webhooks that relies on call status callbacks. |
RTCPeerConnection function | 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 => { call.accept({ rtcConfiguration: { sdpSemantics: 'unified-plan' } // Other options }); }); |
sounds object | A JavaScript object with key/value pairs of sound names (as the key) and URLs (as the value). See the deviceOptions.sounds properties section below for all available properties (keys for the deviceOptions.sounds object) and the default sounds provided by the SDK. Note: The incoming ringtone will loop for at least two seconds and as long as the incoming call is pending. All other sounds will play once; DTMF tones will be cut short if they exceed one second, while outgoing and disconnect sounds will be cut short if they exceed three seconds. |
tokenRefreshMs number default: 10000 | The number of milliseconds before the AccessToken's expiry that the Twilio.Device will emit the 'tokenWillExpire' event. The default is 10 seconds (10000 milliseconds). |
Example:
Specify an Edge location using DeviceOptions
1// pass options object during device instantiation2const device = new Device(token, { edge: 'ashburn' });34// or56// pass options object using the updateOptions method7const device = new Device(token);8device.updateOptions({ edge: 'ashburn' });
Example:
Specify an Edge location and custom sounds
1const deviceOptions = {2edge: 'ashburn',3sounds: {4incoming: 'http://mysite.com/incoming.mp3',5outgoing: 'http://mysite.com/outgoing.mp3',6dtmf8: 'http://mysite.com/8_button.mp3'7}8}91011// pass options object during device instantiation12const device = new Device(token, deviceOptions);1314// or1516// pass options object using the updateOptions method17const device = new Device(token);18device.updateOptions(deviceOptions);
The available properties on the deviceOptions.sounds
object are listed in the left column of the table below. In the right column, there are audio players to hear the default sounds provided by the Voice JavaScript SDK.
deviceOptions.sounds property | Default sound |
---|---|
incoming | |
outgoing | |
disconnect | |
dtmf1 | |
dtmf2 | |
dtmf3 | |
dtmf4 | |
dtmf5 | |
dtmf6 | |
dtmf7 | |
dtmf8 | |
dtmf9 | |
dtmf0 | |
dtmfs (star) | |
dtmfh (hash) |
When deviceOptions.enableImprovedSignalingErrorPrecision
is set to true
, the following errors that would have been described with a generic error code 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
1const device = new Device(token, {2enableImprovedSignalingErrorPrecision: true,3});4device.on('error', (deviceError) => {5// the following table describes how deviceError will change with this feature flag6});
Device Error Name | Flag Enabled | 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
1const device = new Device(token, {2enableImprovedSignalingErrorPrecision: true,3});4const call = device.connect(...);5call.on('error', (callError) => {6// the following table describes how callError will change with this feature flag7});
Call Error Name | Flag Enabled | Flag Disabled |
---|---|---|
GeneralErrors.ConnectionDeclinedError | 31002 | 31005 |
AuthorizationErrors.InvalidJWTTokenError | 31204 | 31005 |
AuthorizationErrors.JWTTokenExpiredError | 31205 | 31005 |
This section contains descriptions of the methods available on a Device
instance.
Add an event listener to the Device
instance. This is an alias for device.on()
.
See the Events section of this page to see the full list of events emitted by a Device
instance.
Parameter | Data Type | Description |
---|---|---|
eventName | string or symbol | The event emitted by the Device instance that will call the listener function |
listener | function | The function that will be called when the specified event is emitted |
Example:
If you want to know when your Device
instance is ready to receive incoming calls, listen for the 'registered'
event.
1const device = new Device(token);23device.addListener('registered', device => {4console.log('The device is ready to receive incoming calls.')5});
See the Node.js Events Docs for more information.
Attempts a new connection to the Twilio application that you associated with the Access Token used when instantiating the Device
instance.
This method will return a Promise with a Call object. You should keep track of this Call
object to monitor/modify the active call.
To end the call, you can use the .disconnect()
method on the Call
object or use the device.disconnectAll()
method.
1const device = new Device(token);23let call = await device.connect({4params: {5To: '+15551234567'6}7});
device.connect()
takes an optional ConnectOptions argument. The ConnectOptions object is a JavaScript object with optional params
, connectToken
, rtcConfiguration
, and rtcConstraints
properties.
Example:
1const device = new Device(token);23let call = await device.connect({4params: {5To: "+15551234567"6agent: "Smith",7location: "Matrix"8},9rtcConstraints: {10audio: true11},12rtcConfiguration: {13iceServers: [{14urls: "stunserver.example.com",15username: "username@twilio.com",16credential: "webrtcCredential"17}]18}19})
The call.connectToken allows for the manual reconnection to an existing call. This is applicable for calls that were previously received (incoming) or created (outgoing) from a Device
instance. When a call is manually reconnected using the call.connectToken, its call.direction property is automatically set to OUTGOING
.
Only unanswered incoming calls can be manually reconnected at this time. Invoking this method to an already answered call may introduce unexpected behavior.
See device's incoming event for an example.
A JavaScript object containing key/value pairs to be sent to the Twilio application. These params
will be passed to your application as GET
or POST
parameters.
The total length of all params
passed to device.connect()
must not exceed 800 bytes. See How to Share Information Between Your Applications for more information.
Your application should not assume that these parameters are safe since any user can call this function with whatever parameters they want.
For example, the following code will pass the params
key/value pairs agent=Smith
and location=Matrix
to the Twilio application associated with this Device
instance's Access Token.
1const device = new Device(token);23let call = await device.connect({4params: {5agent: "Smith",6location: "Matrix"7}8});
An RTCConfiguration dictionary to pass to the RTCPeerConnection constructor. This allows you to configure the WebRTC connection between your local machine and the remote peer.
A MediaStreamConstraints dictionary to pass to getUserMedia when making or accepting a Call. This allows you to configure the behavior of tracks returned in the MediaStream.
Each browser implements a different set of MediaTrackConstraints
, so consult your browser's implementation of getUserMedia
for more information.
Destroys the Device
instance.
This method will disconnect all calls, unbind audio devices, destroy the stream (which causes the unregistered
event to be emitted), and then the Device
instance will emit the destroyed
event. Then, all event listeners attached to the Device
instance are cleaned up.
1const device = new Device(token);23device.destroy();
Disconnect all Calls
associated with the Device
instance.
Example:
A user clicks on a Hang Up button in the browser, which calls device.disconnectAll()
to end the current Call.
1const device = new Device(token);23// A click on a 'Hang Up' button calls this method4const hangupCall = () => {5device.disconnectAll();6console.log('The call has ended.');7}
Calls each of the event listeners registered for the event named eventName
. The listeners will be called in the order they were registered. Any arguments passed in after the eventName
will be passed to the event listeners.
Parameter | Data Type | Description |
---|---|---|
eventName | string or symbol | The event emitted by the Device instance that will call the listener function |
args | any | The arguments that will be passed to the event listener(s) for the specified event |
See the Node.js Events Docs for more information.
Returns an array of event names for which the Device
instance has registered event listeners.
See the Node.js Events Docs for more information.
Returns the current maximum number of event listeners for the Device
instance.
By default, the maximum number of listeners is 10, and is set by the static Device.defaultMaxListeners
property or the dynamic device.setMaxListeners(number)
method.
See the Node.js Events Docs for more information.
Returns the number of listeners listening to the event named eventName
on the Device
instance.
Parameter | Data Type | Description |
---|---|---|
eventName | string or symbol | The name of the event for which you want to retrieve the listener count |
See the Node.js Events Docs for more information.
Returns an array of the listeners registered on the Device
instance for the event named eventName
.
Parameter | Data Type | Description |
---|---|---|
eventName | string or symbol | The name of the event for which you want to retrieve the listeners |
See the Node.js Events Docs for more information.
Removes the listener
for the event named eventName
. This is an alias for device.removeListener()
.
1const device = new Device(token);23const handleSuccessfulRegistration = () => {4console.log('The device is ready to receive incoming calls.')5}67device.on('registered', handleSuccessfulRegistration);89device.off('registered', handleSuccessfulRegistration);
See the Node.js Event Docs for more information.
Add an event listener to the Device
instance. This is analogous to the Device.addListener()
method.
See the Events section of this page to see the full list of events emitted by the Device
instance.
Parameter | Data Type | Description |
---|---|---|
eventName | string or symbol | The event emitted by the Device instance that will call the listener function |
listener | function | The function that will be called when the specified event is emitted |
Example:
If you want to know when your Device
instance is ready to receive incoming calls, listen for the 'registered'
event.
1const device = new Device(token);23device.on('registered', device => {4console.log('The device is ready to receive incoming calls.')5};
Adds a one-time listener to the Device
instance for the event named eventName
.
Parameter | Data Type | Description |
---|---|---|
eventName | string or symbol | The event emitted by the Device instance that will call the listener function |
listener | function | The function that will be called when the specified event is emitted. The listener function will be removed and then invoked one time. |
See the Node.js Events Docs for more information.
Adds a listener function to the beginning of the listeners array for the event named eventName
.
Calling this multiple times with the same eventName
and listener
arguments will add the listener again, meaning that the listener will be called multiple times when the specified event is emitted.
Parameter | Data Type | Description |
---|---|---|
eventName | string or symbol | The event emitted by the Device instance that will call the listener function |
listener | function | The function that will be called when the specified event is emitted. The listener will be added to the beginning of the listeners array for the specified event. |
See the Node.js Events Docs for more information.
Adds a one-time listener to the beginning of the listener array for the specified event.
Parameter | Data Type | Description |
---|---|---|
eventName | string or symbol | The event emitted by the Device instance that will call the listener function |
listener | function | The function that will be called the next time the specified event is emitted. The listener will be removed from the listeners array before being invoked. |
See the Node.js Events Docs for more information.
Returns an array of the listeners associated with the event named eventName
. This includes any wrappers.
Parameter | Data Type | Description |
---|---|---|
eventName | string or symbol | the event for which you want to retrieve the listeners array (includes any wrappers) |
See the Node.js Events Docs for more information.
Register the Device
instance with Twilio, allowing it to receive incoming calls. This will open a signaling WebSocket, so the browser tab may show the 'recording' icon.
It's not necessary to call device.register()
in order to make outgoing calls.
1const device = new Device(token);23const handleSuccessfulRegistration = () => {4console.log('The device is ready to receive incoming calls.')5}67device.on('registered', handleSuccessfulRegistration);89device.register();
Some browsers will throw errors on pages that play audio that isn't initiated by a user gesture. Twilio recommends calling device.register()
in response to a user gesture, such as a click. One popular and intuitive way to implement this is to add a button that will call device.register()
.
Example:
A user clicks on a Start Device button that will fire device.register()
to enable the Device
instance to receive incoming calls. Once registered, the Device
instance will emit the 'registered'
event.
1const device = new Device(token);23// Listen for the 'registered' event4device.on('registered', () => {5console.log('The device is ready to receive calls.')6})78// A 'Start Device' button click calls this method9const startDevice = () => {10console.log('Registering the device to receive calls.');11device.register();12}
Removes all listeners on the Device
instance if no argument is passed. This is not recommended.
The optional eventNames
parameter is an array of event name strings.
If eventNames
argument is passed, only those listeners will be removed. This is only recommended for events and event listeners that you have added, not those created by the SDK.
1const device = new Device(token);23// removes all event listeners4device.removeListeners();56// removes the listeners for the "event1" and "event2" events7device.removeListeners(["event1", "event2"]);
See the Node.js Events Docs for more information.
Removes the listener specified by the eventName
and listener
arguments. This is analogous to device.off()
.
1const device = new Device(token);23const handleSuccessfulRegistration = () => {4console.log('The device is ready to receive incoming calls.')5}67device.on('registered', handleSuccessfulRegistration);89device.removeListener('registered', handleSuccessfulRegistration);
See the Node.js Events Docs for more information.
Set the maximum number of event listeners allowed on this Device
instance. The default maximum is 10.
Calling this method will change only the maximum allowed on this specific instance of a Device
. If you want to change the maximum number of listeners allowed for all Device
instances, consider setting the static Device.defaultMaxListeners
property on the global Device
object provided by the SDK.
Note: device.setMaxListeners(number)
will have precedence over Device.defaultMaxListeners
.
1const device = new Device(token);23device.setMaxListeners(20);
Unregister the Device
instance with Twilio. This will prevent the Device
instance from receiving incoming calls.
The Device
instance will emit the 'unregistered' event when successfully unregistered with Twilio.
1const device = new Device(token);23// Listen for the 'unregistered' event4device.on('unregistered', () => {5console.log('The device is no longer able to receive calls.')6})78const unregisterDevice = () => {9console.log('Unregistering the device.');10device.unregister();11}12
Set the options used within the Device
instance.
See the DeviceOptions section above for the full list of available options.
Example:
Specify an Edge location and custom sounds
1const options = {2edge: 'ashburn',3sounds: {4incoming: '',5outgoing: '',6dtmf8: ''7}8}910const device = new Device(token);11device.updateOptions(options);
Update the token used by this Device
instance to connect to Twilio.
If the token expires, the Device
instance will not be able to receive or make calls. It will also prevent statistics from being sent to Voice Insights.
It is recommended to call this API after device.tokenWillExpire
event is emitted, and before or after a call to prevent a potential ~1s audio loss during the update process.
In the future, as Twilio explores signaling reconnection support, keeping this token updated will be important for automatically restoring connection to a Call
or re-registering the Device
instance.
Example:
1// time to live for the token, in milliseconds2const timeToLive = 600000; // 10 minutes3const refreshBuffer = 30000; // 30 seconds45const token = await getTokenViaAjax({ timeToLive });6const device = new Device(token);78setInterval(async () => {9const newToken = await getTokenViaAjax({ timeToLive });10device.updateToken(token);11}, timeToLive - refreshBuffer);
Emitted when the Device
has been destroyed.
Listen for the 'destroyed'
event.
1const device = new Device(token);23device.on('destroyed', () => {4// Do something5});
Emitted when the Device
instance receives an error.
The event listener will receive a TwilioError
and when applicable, a reference to the Call
object that was active when the error occurred. See the TwilioError section below for more information on the TwilioError
object.
Listen for the 'error'
event.
1const device = new Device(token);23device.on('error', (twilioError, call) => {4console.log('An error has occurred: ', twilioError);5});
TwilioError
The format of the TwilioError
returned from the error event is a JavaScript object with the following properties:
Property | Description |
---|---|
causes string[] | A list of possible causes for the error |
code number | The numerical code associated with this error |
description string | A description of what the error means |
explanation string | An explanation of when the error may be observed |
message string | Any further information discovered and passed along at runtime. |
name string | The name of this error |
originalError (optional) string | The original error received from the external system, if any |
solutions string[] | A list of potential solutions for the error |
See a list of common errors on the Voice SDK Error Codes Page.
Emitted when an incoming Call
is received. An event listener will receive the Call
object representing the incoming Call
. You can interact with the call object using its public APIs, or you can forward it to a different Device
using device.connect() and call.connectToken, enabling your application to receive multiple incoming calls for the same identity.
Important: When forwarding a call, the token for the target Device
instance needs to have the same identity as the token used in the Device
that originally received the call.
1const receiverDevice = new Device(token, options);2await receiverDevice.register();34receiverDevice.on('incoming', (call) => {5// Forward this call to a new Device instance using the call.connectToken string.6forwardCall(call.connectToken);7});89// The forwardCall function may look something like the following.10async function forwardCall(connectToken) {11// For each incoming call, create a new Device object. This ensures individual12// interaction with each call, without affecting other calls.13// IMPORTANT: The token for this new device needs to have the same identity14// as the token used in the receiverDevice.15const device = new Device(token, options);16const call = await device.connect({ connectToken });1718// Destroy the `Device` after the call is completed19call.on('disconnect', () => device.destroy());20}
Emitted when the Device
instance is registered and able to receive incoming calls.
Listen for the 'registered'
event.
1const device = new Device(token);23device.on('registered', () => {4// Do something5});
Emitted when the Device
instance is registering with Twilio to receive incoming calls.
Listen for the 'registering'
event.
1const device = new Device(token);23device.on('registering', () => {4// Do something5});
Emitted when the Device
instance's AccessToken is about to expire.
Use the refreshTokenMs
property on the DeviceOptions object to set a custom warning time. The default is 10 seconds (10000 milliseconds) prior to the AccessToken expiring.
Listen for the 'tokenWillExpire
' event.
You can use this event along with device.updateToken()
to automatically retrieve a new AccessToken and update the AccessToken on the Device instance, as shown in the example below:
1device.on('tokenWillExpire', () => {2const token = getNewTokenViaAjax();3device.updateToken(token);4});
Emitted when the Device
instance has unregistered with Twilio.
Listen for the 'unregistered'
event.
1const device = new Device(token);23device.on('unregistered', () =>4// Do something5});
Return the AudioHelper
object used by the Device
instance. See the device.audio docs for more information.
Returns an array of Call
s that this Device
instance is maintaining.
Modifying one of these calls will have the same affect as modifying the same Call as it was returned by device.on('incoming')
or device.connect()
.
1const device = new Device(token);23// make an ougoing call4device.connect({ params: { To: "+15551234567" } });56console.log(device.calls);78// Prints:9// []
Returns the Edge value the Device
instance is currently connected to. The value will be null when the Device
instance is offline.
1const device = new Device(token);23device.on("registered", () => {4console.log(device.edge);5});67device.register();89// Prints:10// ashburn
Returns the home Twilio Region the Device
instance is connected to as a string. The value will be null
when the Device
instance is offline.
1const device = new Device(token);23console.log(device.home);45// The default region for the JavaScript SDK is US-167// Prints:8// 'us1'9
Returns the identity
string that is associated with the Device
instance's current AccessToken.
This accessor is only populated when the Device
instance has successfully registered with Twilio.
Returns a Boolean for whether the Device
instance is currently on an active Call
1const device = new Device(token);23console.log(device.isBusy);45// Prints:6// false78910// make an outgoing call11device.connect({ params: { To: "+15551234567" });1213console.log(device.isBusy);1415// Prints:16// true
Returns the state of the Device
instance
1const device = new Device(token);23console.log(device.state);45// Prints:6// unregistered
The possible Device
instance states are:
unregistered
- The
Device
instance is not registered with Twilio and cannot accept incoming calls
registering
- The
Device
instance is registering with Twilio to accept incoming calls
registered
- The
Device
instance is registered with Twilio and can accept incoming calls
destroyed
- The
Device
instance has been destroyed and will not be able to make or receive new calls
Use event listeners on the Device
instance to give the user feedback when the Device
instance's state changes. See the Best Practices Page for more information.
Returns the token used by this Device
instance
1const device = new Device(token);23console.log(device.token);45// Prints:6// eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp....
You can use the JWT debugger to decode and inspect the token.
Static methods should be called on the Device
global object provided by the SDK.
Returns a PreflightTest
object representing a test call to Twilio which provides information to help troubleshoot call related issues.
Example:
const preflightTest = Device.runPreflight(token, options);
A Twilio.PreflightTest
object represents a test call to Twilio which provides information to help troubleshoot call related issues. You never instantiate it directly, but it's returned when you call Device.runPreflight(token, options)
.
See the PreflightTest Page for more information.
Static properties are those properties that only exist on the global Device
object.
Use this to change the default maximum number of event listeners permitted on all instances of a Device
.
Device.defaultMaxListeners = 20;
If you need to change the maximum number of event listeners on a specific Device
instance, call the device.setMaxListeners(number)
method on that instance.
Note: device.setMaxListeners(number)
will have precedence over Device.defaultMaxListeners
.
Static accessors should be called on the Device
global provided by the SDK.
Returns a Boolean for whether or not this SDK is supported by the current browser
1console.log(Device.isSupported);23// Prints:4// true5
Returns the package name of the SDK
1console.log(Device.packageName);23// Prints:4// @twilio/voice-sdk5
Returns the current SDK version
1console.log(Device.version);23// Prints:4// 2.0.0