Voice JS SDK v1: Twilio.Device

The following is a list of methods available on Twilio.Device:

As of 1.5.0, the Twilio.Device class can be constructed directly rather than used as a singleton via the Twilio.Device global. Using this method, multiple Device instances can operate on the same page simultaneously. If a token is passed, Device.setup() will be run on construction with the passed token and options. Otherwise, the new Device will wait for Device.setup(token, options) to be called before initiating a signaling connection.

1
const device = new Twilio.Device();
2
device.setup(token, options);
3

4
// or (deprecated singleton behavior)...
5

6
Twilio.Device.setup(token, options);

Initialize Twilio.Device with an Access Token (see Twilio Access Tokens). The token you provide will activate the Device, give it an identity, grant it privileges to make and receive inbound and/or outbound calls, and associate it with a specific Twilio application. You should call this before anything else. If your token allows inbound client connections, the device will start listening for new connections when you call .setup().

Browsers are cracking down on unwarranted background audio. As a result, browsers are progressively moving toward requiring a user gesture before allowing audio to play on a page. Twilio recommends calling Device.setup() in response to a user gesture, such as a click. One popular and intuitive way to implement this is to add a "ready" button that will initiate the Device and show the dialer once clicked.

.setup()'s params argument takes a JavaScript object containing configuration settings. Available settings are listed below:

For example:

Twilio.Device.setup(token); // use the default parameters

Or using params:

1
// enable debug logging and use default values for all other parameters
2
Twilio.Device.setup(token, { debug: true });

Or using custom sounds:

1
Twilio.Device.setup(token, {
2
  sounds: {
3
    incoming: 'http://mysite.com/incoming.mp3',
4
    outgoing: 'http://mysite.com/outgoing.mp3',
5
    dtmf8: 'http://mysite.com/funny_noise.mp3'
6
  }
7
}

Or specify an Edge location to connect to:

1
// edge as a string
2
Twilio.Device.setup(token, { edge: 'ashburn' });
3

4
// edge with auto fallback functionality
5
Twilio.Device.setup(token, { edge: ['ashburn', 'sydney' ] });
6

7
// edge with auto fallback functionality for private interconnect
8
Twilio.Device.setup(token, { edge: ['ashburn', 'san-jose-ix' ] });

Attempts a new connection to the Twilio application that you associated with this Device's Access Token when you called .setup() (see Access Tokens for more information).

The optional params argument is a JavaScript object which will be passed to your application as POST/GET parameters. Note, the total length of all parameters passed in must not exceed 800 bytes. See How to Share Information Between Your Applications for more information.

For example, the following code will pass the parameters agent=Smith and location=Matrix to the Twilio application associated with this Device's Access Token.

1
var connection = Twilio.Device.connect({
2
  agent: "Smith",
3
  location: "Matrix"
4
});
5

You can also specify an audioConstraints object to change the behavior of the local media stream during this call. You can use this to select a specific microphone, or turn off features like auto-gain control. Each web browser implements a different set of MediaTrackConstraints which may be used as audioConstraints, so consult your browser's implementation of getUserMedia for further details.

1
var audioConstraints = {
2
  optional: [{ sourceId: 'XXX' }]
3
};
4

5
var connection = Twilio.Device.connect(null, audioConstraints);

The .connect() method returns a Twilio.Connection object. You can end the connection by calling its .disconnect() method.

When you call .connect(), the client will attempt a new connection to the Twilio Application you use in your Twilio.Device's access token. This application can do whatever you like: Make a phone call to a phone number or Twilio Client address, start a conference call, interact with an IVR, etc.

For example, if your application's VoiceUrl returns the following TwiML:

1
<Response>
2
  <Dial callerId="+1888XXXXXXX">
3
    415-867-5309
4
  </Dial>
5
</Response>

then your device will make a call to 415-867-5309 every time you call .connect().

All of TwiML is available to your client applications.

You can use the params passed to the application in .connect() to dynamically generate the right TwiML for your app. For example, you could do the following in your JavaScript code:

1
var number = '5558675309';
2
var connection = Twilio.Device.connect({
3
  phone: number
4
});

And in the web application that generates your TwiML, retrieve the phone parameter from the HTTP request and insert into your TwiML as follows:

1
<Response>
2
  <Dial callerId="+1888XXXXXXX">
3
    5558675309
4
  </Dial>
5
</Response>

Returns the active connection object. Connection objects can be used to perform operations on the connection like mute, unmute, sending DTMF digits, etc.

Destroys the device. Terminates active and pending connections, and cleans up all event listeners attached to the Device, after triggering the offline event handler. Device will not be able to make or receive new connections until you call Device.setup() again.

Terminates the active connection. This will trigger the disconnect event handler. It will not prevent new incoming connections.

Return the status of the device. The status will be one of the following strings:

Returns a PreflightTest object representing a test call to Twilio which provides information to help troubleshoot call related issues. For example:

1
import { Device, PreflightTest } from 'twilio-client';
2

3
const preflightTest = Device.runPreflight(token, options);
4

5
preflightTest.on(PreflightTest.Events.Completed, (report) => {
6
  console.log(report);
7
});
8

9
preflightTest.on(PreflightTest.Events.Failed, (error) => {
10
  console.log(error);
11
});

The token parameter is passed directly to the Device's constructor and will be used to connect to a TwiML app that you associated with your token. In order to get better results, the TwiML app should be able to record audio from a microphone and play it back to the browser. Please see Preflight Test TwiML Apps for details.

The options parameter is a JavaScript object containing configuration settings. Available settings are listed below:

Note that any event handlers set here will be removed when calling Device.destroy().

This is triggered when an incoming connection is canceled by the caller before it is accepted by the Twilio Client device.

The handler function receives a Twilio.Connection object as an argument. Since this Connection object represents an inactive connection, you'll probably just want to use the event to update your application's UI, then throw away the Connection and wait for the next call.

This is triggered when a connection is opened, whether initiated using .connect() or via an accepted incoming connection.

The handler function receives a Twilio.Connection object as an argument.

Fired any time a Connection is closed. The handler function receives the Twilio.Connection object that was just closed as an argument.

Emitted when any device error occurs. These may be errors in your request, your token, connection errors, or other application errors. See the Twilio Client error code reference for more information. Using the error handler is a great way to debug your application and help catch mistakes in your code.

The handler function receives an error object as an argument. The error object may include the following properties:

1
Twilio.Device.on('error', function(error) {
2
  console.log(error.message);
3
});

This is triggered whenever an incoming connection from an outbound REST call or a TwiML <Dial> to this device is made.

The handler function receives a Twilio.Connection object as an argument. This connection will be in state pending until you call .accept() on it.

1
Twilio.Device.on('incoming', function(connection) {
2
  connection.accept();
3
  // do awesome ui stuff here
4
  // $('#call-status').text("you're on a call!");
5
});

This is triggered when the connection to Twilio drops or the device's token is invalid/expired. In either of these scenarios, the device cannot receive incoming connections or make outgoing connections. If the token expires during an active connection the offline event will be fired, but the connection will not be terminated. In this situation you will have to call Twilio.Device.setup() with a valid token before attempting or receiving the next connection.

The handler function receives the Twilio.Device object as its sole argument.

This is initially triggered when all operations in .setup() have completed and the device is ready and online. It will be triggered again if the device goes offline and comes back online (i.e. the connection drops and returns).

The handler function receives the Twilio.Device object as its sole argument.

1
Twilio.Device.on('ready', function(device) {
2
  // The device is now ready
3
  console.log("Twilio.Device is now ready for connections");
4
});

Device.isSupported is a Boolean value which indicates whether WebRTC is supported by the browser or not. If false, it's an indicator that Device.setup should not be called or else it will throw an unsupported exception.

Device.packageName returns the npm package name. This can be used to get the logger instance used by the SDK. See SDK Logger for details.

Example:

1
import { getLogger } from 'loglevel';
2
const logger = getLogger(Device.packageName);

Device.version returns the current version of the SDK.

By default, the SDK automatically reconnects the WebSocket connection to the same edge location when it is unreachable, or when the SDK encounters a network error that results in a WebSocket disconnect. But if Twilio.Device.Options.edge parameter is supplied as an array of edge names, the SDK will enable automatic Edge fallback functionality. The diagram below illustrates the logic that is executed to perform the fallback.

Expand image

During initialization, the SDK will use the first edge name in the Twilio.Device.Options.edge array. If the SDK encounters an error that results in a WebSocket disconnect with error code 1006 or 1015, the SDK will attempt reconnection to the next Edge in the array using an exponential backoff timer with an initial value of 1+random(5) and a maximum of 20 seconds. This maximum delay can be configured via Twilio.Device.Options.backoffMaxMs parameter.

If the SDK encounters an error while already connected to an edge server, the SDK will try to reconnect to the same edge once before attempting to connect to the next edge.

The following table provides common scenarios for when a fallback may occur:

It's important to note that "unreachable" in these scenarios means the SDK failed to establish a WebSocket connection to the edge endpoint which resulted in error code 1006 or 1015. The error code 1015 is a WebSocket close event which is raised when the connection fails to perform a TLS handshake. This happens if the server certificate is invalid or cannot be verified. While the error code 1006 is raised when the connection was dropped unexpectedly and there is no close frame received from the server. The following are common issues that causes 1006:

• The domain name cannot be resolved by the DNS
• The network cannot reach the endpoint due to, for example, a misconfigured firewall
• The client becomes offline due to, for example, the local device losing network connectivity, and
• In an unlikely and very rare scenario, the Edge and standby servers are down

Prior to version 1.10.0, Voice Client JS logging could only be configured during Device.setup using debug and warnings flag. Starting 1.10.0, Voice Client JS exposes a loglevel based logger which allows for runtime logging configuration that includes setting the log level to "trace", "debug", "info", "warn" and "error". Loglevel is a versatile logger library that includes level-based logging and filtering, and provides a plugin API to enable functionality such as sending the log messages to a log server.

For example, to enable logging:

1
import { getLogger } from 'loglevel';
2

3
const logger = getLogger(Device.packageName);
4
// Set log level on subsequent page loads and refreshes
5
logger.setLevel('DEBUG');

The Device.audio object lets you control the way Twilio Client interacts with speaker and microphone resources. Device.audio is an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter), and as such its events can be subscribed to viaDevice.audio.on(eventName, handler).

NOTE: Many of audio features are browser-dependent.

Currently Chrome 49+ is the only browser that fully supports Twilio.Device.audio.

Audio output selection requires support for setSinkId. At the time of writing, this method is only supported in Chrome 49 and above, and Microsoft Edge. As Firefox adds support for these APIs, twilio.js will be updated to provide support. Although Edge supports setSinkId, it is not yet fully supported in this API.

Audio input selection requires support for AudioContext. This feature is supported in latest modern browsers (Chrome, Firefox, Edge), however twilio.js has not completed implementation in Firefox and Edge. Support is coming soon.

If these features are used in a browser that does not support them, the get method will return an empty Set, whereas the set and test methods will return a rejected Promise.

Set the MediaTrackConstraints to be applied on every getUserMedia call for new input device audio. Any deviceId specified here will be ignored. Instead, device IDs should be specified using .audio.setInputDevice(). The returned Promise resolves when the media is successfully reacquired, or immediately if no input device is set.

Set the current input device by deviceId. Once this is set, the input device will be used in the current call, if any, and used by default for any subsequent calls. In addition, whenever an inputDevice is set, the Device.audio#inputVolume event will fire on every animation frame. Returns a Promise that resolves if the input device was set successfully.

Note: This is not supported in Firefox (as recent as 51) due to its lack of support for multiple input devices.

Unset the MediaTrackConstraints to be applied on every getUserMedia call for new input device audio. The returned Promise resolves when the media is successfully reacquired, or immediately if no input device is set.

Unset the active input device. This will stop the Device.audio#inputVolume polling, and stop the input stream.

The currently set input audio MediaTrackConstraints set by setAudioConstraints(). Starts as null.

A Map containing the MediaDeviceInfo object of all available output devices (hardware devices capable of outputting audio), indexed by deviceId.

Note: Due to browser-imposed security restrictions, MediaDeviceInfos available in availableOutputDevices may contain auto-generated labels (e.g. "Unknown Audio Output Device 1"), or an incomplete / empty list of devices, until the user grants the application access to these resources in response to a call to the browser's getUserMedia() API. In an effort to reduce device fingerprinting, all major browsers are getting more strict in this regard. We strongly recommend your application calls getUserMedia() before rendering your input / output device selection UI for the cleanest user experience.

Also Note: Firefox (as recent as 51) does not list any audiooutput devices, and Edge (as recent as 38) does not label its audiooutput devices even after user permission is granted.

After the user accepts the getUserMedia() prompt, the ``AudioHelper#deviceChange event will be fired to indicate that the application UI should be updated.

A Map containing the MediaDeviceInfo object of all available input devices (hardware devices capable of providing an input audio stream), indexed by deviceId.

Note: Due to browser-imposed security restrictions, MediaDeviceInfos available in availableInDevices may contain auto-generated labels (e.g. "Unknown Audio Input Device 1"), or an incomplete / empty list of devices, until the user grants the application access to these resources in response to a call to the browser's getUserMedia() API. In an effort to reduce device fingerprinting, all major browsers are getting more strict in this regard. We strongly recommend your application calls getUserMedia() before rendering your input / output device selection UI for the cleanest user experience.

After the user accepts the getUserMedia() prompt, the ``AudioHelper#deviceChange event will be fired to indicate that the application UI should be updated.

A MediaDeviceInfo representing the input device selected by .audio.setInputDevice(), or null.

speakerDevices is an AudioOutputCollection that controls which output devices are used to play standard speaker sounds: the ringtone you hear when initiating a call, the disconnect sound, DTMF tones the user might press and the audio received from the remote participant. Changing this set of devices will switch the device(s) used for these sounds. If you change these during an active call, the remote participant's audio will immediately be played through the new set of outputs.

Note: This is not supported in Firefox (as recent as 51) or Edge (as recent as 38) due to their lack of support for HTMLAudioElement.setSinkId().

``ringtoneDevices is an AudioOutputCollection that controls which output devices are used to play the ringing sound when receiving an incoming call. Changing this set of devices will switch the devices used for the incoming call sound.

Note: This is not supported in Firefox (as recent as 51) or Edge (as recent as 38) due to their lack of support for HTMLAudioElement.setSinkId().

Use the test() method on the speakderDevices or ringtoneDevices collections to play a test sound. This is a great way to let your user evaluate whether the device is working as expected by giving them audible feedback on the device configuration.

1
// Test that the devices have been set properly by playing 'outgoing' sound...
2
Twilio.Device.audio.speakerDevices.test();
3
// ... or test playback using a custom sound
4
Twilio.Device.audio.speakerDevices.test('cowbell.mp3');

.audio.on('deviceChange', handler(lostActiveDevices))

Register a handler that will be fired whenever a new audio device is found, an existing audio device is lost or the label of an existing device is changed. This typically happens when the user plugs in or unplugs an audio device, like a headset or a microphone. This will also trigger after the customer has given access to user media via ``getUserMedia for the first time, as the labels will become populated. If you want to allow users to choose a specific audio device in your application's UI, attach a listener to this event.

Note that this does not detect a customer plugging in headphones or other speakers through the headphone jack, as the headphone jack only redirects audio from the internal audio device.

The parameter, lostActiveDevices, is an array of [MediaDeviceInfo](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo) objects that represents all devices that were currently active in either.speakerDevices or ``.ringtoneDevices at the time they were lost, if any. A non-empty array is an indicator that the user's experience was likely affected by this event.

.audio.on('inputVolume', handler(volume))

Register a handler that will be fired every animation frame with the current volume of the selected input device, if one is set. The handler will be invoked up to 60 times per second, and will scale down dynamically on slower devices to preserve performance. The handler receives volume as a percentage of maximum volume represented by a floating point number between 0.0 and 1.0, inclusive. This value represents a range of relative decibel values between -100dB and -30dB.

Note: This will never in Firefox (as recent as 51) as there is no supported way to set the input device.

Both speakerDevices and ringtoneDevices are instances of AudioOutputCollection . An AudioOutputCollection represents active audio devices, and can be updated to redirect speaker and ringtone sounds to different devices in realtime.

Get a Set containing MediaDeviceInfo objects representing the active devices in the collection.

Replace the active devices in the collection by passing one or more device IDs. Returns a Promise, which is fulfilled if the device(s) were set successfully and rejected if:

• Output selection is not supported by the browser or
• A specified deviceId wasn't found or
• No deviceIds were specified

Test the active devices by playing a sound through them. Optionally, a URL can be passed to play a custom test sound. Returns a Promise, which is fulfilled if the devices were set successfully and rejected if:

• Output selection is not supported by the browser or
• There are no active devices or
• Client detects one or more devices failed to play

These getters/setters were moved over from the deprecated ``Device.sounds API. If a sound is disabled, it will not be played through any output device.

.audio.incoming( [bool] )

Enable or disable the incoming event sound.

.audio.incoming()

Returns a Boolean indicating whether the incoming sound is enabled or disabled.

.audio.outgoing( [bool] )

Enable or disable the outgoing event sound.

.audio.outgoing()

Returns a Boolean indicating whether the outgoing sound is enabled or disabled.

.audio.disconnect( [bool] )

Enable or disable the disconnect event sound.

.audio.disconnect()

Returns a Boolean indicating whether the disconnect sound is enabled or disabled.

twilio.js 1.3 and below exposed a sounds object on the Device. In twilio.js 1.4 and above,sounds and all of the methods defined on sounds have been moved toaudio. sounds and the old versions of these methods remain available in twilio.js 1.4, but calling the methods onsounds will generate a deprecation warning. We strongly encourage you to begin using ``audio.

Additionally, Twilio Client is moving toward the standard EventEmitter interface, meaning events should be managed with .on(eventName, handler) and .removeListener(eventName, handler), replacing our legacy handlers (such as .accept(handler), .error(handler), etc...). The following methods are deprecated:

1
Device.cancel(handler)
2
Device.connect(handler)
3
Device.disconnect(handler)
4
Device.error(handler)
5
Device.incoming(handler)
6
Device.offline(handler)
7
Device.ready(handler)

These have been replaced with the following events:

1
Device.on('cancel', handler)
2
Device.on('connect', handler)
3
Device.on('disconnect', handler)
4
Device.on('error', handler)
5
Device.on('incoming', handler)
6
Device.on('offline', handler)
7
Device.on('ready', handler)