Voice JavaScript SDK: Twilio.Device

• Instantiate a Device
• DeviceOptions
• Methods
• Events
• Accessors
• Static Methods
• Static Properties
• Static Accessors

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.

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 location
2
const device = new Device(token, { edge: 'ashburn'});
3

4
// Instantiate the device with a specified edge and auto-fallback functionality
5
const 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().

1
const deviceOptions = {
2
  edge: 'ashburn',
3
}
4

5
// pass the options object as the second argument in Device constructor
6
const device = new Device(token, deviceOptions);
7

8
// or
9

10
// use the updateOptions method after instantiating the device
11
const device = new Device(token);
12
device.updateOptions(deviceOptions);

DeviceOptions is a JavaScript object with the properties listed in the table below. All properties are optional.

Example:

Specify an Edge location using DeviceOptions

1
// pass options object during device instantiation
2
const device = new Device(token, { edge: 'ashburn' });
3

4
// or
5

6
// pass options object using the updateOptions method
7
const device = new Device(token);
8
device.updateOptions({ edge: 'ashburn' });

Example:

Specify an Edge location and custom sounds

1
const deviceOptions = {
2
  edge: 'ashburn',
3
  sounds: {
4
    incoming: 'http://mysite.com/incoming.mp3',
5
    outgoing: 'http://mysite.com/outgoing.mp3',
6
    dtmf8: 'http://mysite.com/8_button.mp3'
7
  }
8
}
9

10

11
// pass options object during device instantiation
12
const device = new Device(token, deviceOptions);
13

14
// or
15

16
// pass options object using the updateOptions method
17
const device = new Device(token);
18
device.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.

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

1
const device = new Device(token, {
2
  enableImprovedSignalingErrorPrecision: true,
3
});
4
device.on('error', (deviceError) => {
5
  // the following table describes how deviceError will change with this feature flag
6
});

Call Error Changes

1
const device = new Device(token, {
2
  enableImprovedSignalingErrorPrecision: true,
3
});
4
const call = device.connect(...);
5
call.on('error', (callError) => {
6
  // the following table describes how callError will change with this feature flag
7
});

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.

Example:

If you want to know when your Device instance is ready to receive incoming calls, listen for the 'registered' event.

1
const device = new Device(token);
2

3
device.addListener('registered', device => {
4
  console.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.

1
const device = new Device(token);
2

3
let call = await device.connect({
4
  params: {
5
    To: '+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:

1
const device = new Device(token);
2

3
let call = await device.connect({
4
  params: {
5
    To: "+15551234567"
6
    agent: "Smith",
7
    location: "Matrix"
8
  },
9
  rtcConstraints: {
10
    audio: true
11
  },
12
  rtcConfiguration: {
13
    iceServers: [{
14
      urls: "stunserver.example.com",
15
      username: "username@twilio.com",
16
      credential: "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.

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.

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.

1
const device = new Device(token);
2

3
let call = await device.connect({
4
  params: {
5
    agent: "Smith",
6
    location: "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.

1
const device = new Device(token);
2

3
device.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.

1
const device = new Device(token);
2

3
// A click on a 'Hang Up' button calls this method
4
const hangupCall = () => {
5
 device.disconnectAll();
6
 console.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.

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.

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.

See the Node.js Events Docs for more information.

Removes the listener for the event named eventName. This is an alias for device.removeListener().

1
const device = new Device(token);
2

3
const handleSuccessfulRegistration = () => {
4
  console.log('The device is ready to receive incoming calls.')
5
}
6

7
device.on('registered', handleSuccessfulRegistration);
8

9
device.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.

Example:

If you want to know when your Device instance is ready to receive incoming calls, listen for the 'registered' event.

1
const device = new Device(token);
2

3
device.on('registered', device => {
4
  console.log('The device is ready to receive incoming calls.')
5
};

Adds a one-time listener to the Device instance for the event named eventName.

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.

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.

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.

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.

1
const device = new Device(token);
2

3
const handleSuccessfulRegistration = () => {
4
  console.log('The device is ready to receive incoming calls.')
5
}
6

7
device.on('registered', handleSuccessfulRegistration);
8

9
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.

1
const device = new Device(token);
2

3
// Listen for the 'registered' event
4
device.on('registered', () => {
5
  console.log('The device is ready to receive calls.')
6
})
7

8
// A 'Start Device' button click calls this method
9
const startDevice = () => {
10
  console.log('Registering the device to receive calls.');
11
  device.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.

1
const device = new Device(token);
2

3
// removes all event listeners
4
device.removeListeners();
5

6
// removes the listeners for the "event1" and "event2" events
7
device.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().

1
const device = new Device(token);
2

3
const handleSuccessfulRegistration = () => {
4
  console.log('The device is ready to receive incoming calls.')
5
}
6

7
device.on('registered', handleSuccessfulRegistration);
8

9
device.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.

1
const device = new Device(token);
2

3
device.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.

1
const device = new Device(token);
2

3
// Listen for the 'unregistered' event
4
device.on('unregistered', () => {
5
  console.log('The device is no longer able to receive calls.')
6
})
7

8
const unregisterDevice = () => {
9
  console.log('Unregistering the device.');
10
  device.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

1
const options = {
2
  edge: 'ashburn',
3
  sounds: {
4
    incoming: '',
5
    outgoing: '',
6
    dtmf8: ''
7
  }
8
}
9

10
const device = new Device(token);
11
device.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 milliseconds
2
const timeToLive = 600000; // 10 minutes
3
const refreshBuffer = 30000; // 30 seconds
4

5
const token = await getTokenViaAjax({ timeToLive });
6
const device = new Device(token);
7

8
setInterval(async () => {
9
  const newToken = await getTokenViaAjax({ timeToLive });
10
  device.updateToken(token);
11
}, timeToLive - refreshBuffer);

Emitted when the Device has been destroyed.

Listen for the 'destroyed' event.

1
const device = new Device(token);
2

3
device.on('destroyed', () => {
4
    // Do something
5
});

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.

1
const device = new Device(token);
2

3
device.on('error', (twilioError, call) => {
4
 console.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:

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.

1
const receiverDevice = new Device(token, options);
2
await receiverDevice.register();
3

4
receiverDevice.on('incoming', (call) => {
5
  // Forward this call to a new Device instance using the call.connectToken string.
6
  forwardCall(call.connectToken);
7
});
8

9
// The forwardCall function may look something like the following.
10
async function forwardCall(connectToken) {
11
  // For each incoming call, create a new Device object. This ensures individual
12
  // interaction with each call, without affecting other calls.
13
  // IMPORTANT: The token for this new device needs to have the same identity
14
  // as the token used in the receiverDevice.
15
  const device = new Device(token, options);
16
  const call = await device.connect({ connectToken });
17

18
  // Destroy the `Device` after the call is completed
19
  call.on('disconnect', () => device.destroy());
20
}

Emitted when the Device instance is registered and able to receive incoming calls.

Listen for the 'registered' event.

1
const device = new Device(token);
2

3
device.on('registered', () => {
4
    // Do something
5
});

Emitted when the Device instance is registering with Twilio to receive incoming calls.

Listen for the 'registering' event.

1
const device = new Device(token);
2

3
device.on('registering', () => {
4
    // Do something
5
});

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:

1
device.on('tokenWillExpire', () => {
2
  const token = getNewTokenViaAjax();
3
  device.updateToken(token);
4
});

Emitted when the Device instance has unregistered with Twilio.

Listen for the 'unregistered' event.

1
const device = new Device(token);
2

3
device.on('unregistered', () =>
4
    // Do something
5
});

Return the AudioHelper object used by the Device instance. See the device.audio docs for more information.

Returns an array of Calls 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().

1
const device = new Device(token);
2

3
// make an ougoing call
4
device.connect({ params: { To: "+15551234567" } });
5

6
console.log(device.calls);
7

8
// Prints:
9
// []

Returns the Edge value the Device instance is currently connected to. The value will be null when the Device instance is offline.

1
const device = new Device(token);
2

3
device.on("registered", () => {
4
  console.log(device.edge);
5
});
6

7
device.register();
8

9
// 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.

1
const device = new Device(token);
2

3
console.log(device.home);
4

5
// The default region for the JavaScript SDK is US-1
6

7
// 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

1
const device = new Device(token);
2

3
console.log(device.isBusy);
4

5
// Prints:
6
// false
7

8

9

10
// make an outgoing call
11
device.connect({ params: { To: "+15551234567" });
12

13
console.log(device.isBusy);
14

15
// Prints:
16
// true

Returns the state of the Device instance

1
const device = new Device(token);
2

3
console.log(device.state);
4

5
// 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

1
const device = new Device(token);
2

3
console.log(device.token);
4

5
// 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

1
console.log(Device.isSupported);
2

3
// Prints:
4
// true
5

Returns the package name of the SDK

1
console.log(Device.packageName);
2

3
// Prints:
4
// @twilio/voice-sdk
5

Returns the current SDK version

1
console.log(Device.version);
2

3
// Prints:
4
// 2.0.0