Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Voice JS SDK v1: Twilio.PreflightTest


(warning)

Warning

You're viewing the 1.X version of the Voice JavaScript SDK (formerly called Twilio Client). Click here for information on how to migrate to the 2.X version.

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 Twilio.Device.runPreflight(token, options).


_11
import { Device, PreflightTest } from 'twilio-client';
_11
_11
const preflightTest = Device.runPreflight(token, options);
_11
_11
preflightTest.on(PreflightTest.Events.Completed, (report) => {
_11
console.log(report);
_11
});
_11
_11
preflightTest.on(PreflightTest.Events.Failed, (error) => {
_11
console.log(error);
_11
});


Method Reference

method-reference page anchor

.stop()

stop page anchor

Calling this method from the PreflightTest object will stop the existing test and will raise a failed event with an error code 31008 indicating that the call has been cancelled.


.on('completed', handler(report))

completed-handler page anchor

Raised when PreflightTest.status has transitioned to PreflightTest.Status.Completed. During this time, the report is available and ready to be inspected. This will not trigger if a fatal error is encountered during the test. Example report:


_159
{
_159
"callSid": "CAa6a7a187a9cba2714d6fdccf472cc7b1",
_159
_159
/**
_159
* The quality of the call, determined by the MOS (Mean Opinion Score) of the audio stream. Possible values include
_159
* PreflightTest.CallQuality.Excellent - If the average mos is over 4.2
_159
* PreflightTest.CallQuality.Great - If the average mos is between 4.1 and 4.2 both inclusive
_159
* PreflightTest.CallQuality.Good - If the average mos is between 3.7 and 4.0 both inclusive
_159
* PreflightTest.CallQuality.Fair - If the average mos is between 3.1 and 3.6 both inclusive
_159
* PreflightTest.CallQuality.Degraded - If the average mos is 3.0 or below
_159
*/
_159
"callQuality": "excellent",
_159
_159
/**
_159
* An array of WebRTC stats for the ICE candidates gathered when connecting to media.
_159
* Each item is an RTCIceCandidateStats object which provides information related to an ICE candidate.
_159
* See RTCIceCandidateStats for more details https://developer.mozilla.org/en-US/docs/Web/API/RTCIceCandidateStats
_159
*/
_159
"iceCandidateStats": [...]
_159
_159
/**
_159
* A WebRTC stats for the ICE candidate pair used to connect to media, if candidates were selected.
_159
* Each item is an RTCIceCandidateStats object which provides information related to an ICE candidate.
_159
* See RTCIceCandidateStats for more details https://developer.mozilla.org/en-US/docs/Web/API/RTCIceCandidateStats
_159
*/
_159
"selectedIceCandidatePairStats": {
_159
"localCandidate": {...},
_159
"remoteCandidate": {...}
_159
}
_159
_159
/**
_159
* Whether a TURN server is required to connect to media.
_159
* This is dependent on the selected ICE candidates, and will be true if either is of type "relay",
_159
* false if both are of another type, or undefined if there are no selected ICE candidates.
_159
* See `PreflightTest.Options.iceServers` for more details.
_159
*/
_159
"isTurnRequired": false,
_159
_159
/**
_159
* Network related time measurements which includes millisecond timestamps
_159
* and duration for each type of connection.
_159
*/
_159
"networkTiming": {
_159
/**
_159
* Measurements for establishing DTLS connection.
_159
* This is measured from RTCDtlsTransport `connecting` to `connected` state.
_159
* See RTCDtlsTransport state
_159
* https://developer.mozilla.org/en-US/docs/Web/API/RTCDtlsTransport/state.
_159
*/
_159
"dtls": {
_159
"start": 1584573229981,
_159
"end": 1584573230166,
_159
"duration": 185
_159
},
_159
_159
/**
_159
* Measurements for establishing ICE connection.
_159
* This is measured from ICE connection `checking` to `connected` state.
_159
* See RTCPeerConnection.iceConnectionState
_159
* https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/iceConnectionState.
_159
*/
_159
"ice": {
_159
"start": 1584573229898,
_159
"end": 1584573229982,
_159
"duration": 84
_159
},
_159
_159
/**
_159
* Measurements for establishing a PeerConnection.
_159
* This is measured from PeerConnection `connecting` to `connected` state.
_159
* See RTCPeerConnection.connectionState
_159
* https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/connectionState.
_159
*/
_159
"peerConnection": {
_159
"start": 1584573229902,
_159
"end": 1584573230167,
_159
"duration": 265
_159
},
_159
_159
/**
_159
* Measurements for establishing Signaling connection.
_159
* This is measured from initiating a connection using `device.connect()`,
_159
* up to when RTCPeerConnection.signalingState transitions to `stable` state.
_159
* See RTCPeerConnection.signalingState
_159
* https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/signalingState
_159
*/
_159
"signaling": {
_159
"start": 1595885835227,
_159
"end": 1595885835573,
_159
"duration": 346
_159
}
_159
},
_159
_159
/**
_159
* RTC related stats that are extracted from WebRTC samples.
_159
* This information includes maximum, minimum, and average values calculated for each stat.
_159
*/
_159
"stats": {
_159
"jitter": {
_159
"average": 35,
_159
"max": 35,
_159
"min": 35
_159
},
_159
"mos": {
_159
"average": 2,
_159
"max": 2,
_159
"min": 2
_159
},
_159
"rtt": {
_159
"average": 80.33,
_159
"max": 88,
_159
"min": 77
_159
}
_159
},
_159
_159
/**
_159
* Timing measurement related to the test.
_159
* Includes millisecond timestamps and duration.
_159
*/
_159
"testTiming": {
_159
"start": 1584573229085,
_159
"end": 1584573242279,
_159
"duration": 13194
_159
},
_159
_159
/**
_159
* Calculated totals in RTC statistics samples.
_159
*/
_159
"totals": {
_159
"bytesReceived": 62720,
_159
"bytesSent": 93760,
_159
"packetsLost": 0,
_159
"packetsLostFraction": 0,
_159
"packetsReceived": 392,
_159
"packetsSent": 586
_159
},
_159
_159
/**
_159
* Array of samples collected during the test.
_159
* See sample object format here
_159
* https://www.twilio.com/docs/voice/sdks/javascript/v1/connection#sample
_159
*/
_159
"samples": [...],
_159
_159
/**
_159
* The edge passed to `Device.runPreflight`.
_159
*/
_159
"selectedEdge": "roaming",
_159
_159
/**
_159
* The edge that the test call was connected to.
_159
*/
_159
"edge": "ashburn",
_159
_159
/**
_159
* PreflightTest.Warnings detected during the test.
_159
*/
_159
"warnings": [...]
_159
}

.on('connected', handler())

connected-handler page anchor

Raised when PreflightTest.status has transitioned to PreflightTest.Status.Connected. This indicates that the connection to Twilio has been established.

.on('failed', handler(error))

failed-handler page anchor

Raised when PreflightTest.status has transitioned to PreflightTest.Status.Failed. This happens when establishing a connection to Twilio has failed or when a test call has encountered a fatal error. This is also raised if PreflightTest.stop is called while the test is in progress. The error emitted from this event is coming from Device.on('error') and uses the same error format.

.on('sample', handler(sample))

sample-handler page anchor

This event is published every second and is raised when the Connection gets a webrtc sample object. The sample object is coming from Connection.on('sample') and uses the same sample format.

.on('warning', handler(warning))

warning-handler page anchor

Raised whenever the test encounters a warning. Example warning data:


_18
{
_18
/**
_18
* Name of the warning.
_18
* See https://www.twilio.com/docs/voice/insights/call-quality-events-twilio-client-sdk
_18
*/
_18
name: 'insights-connection-error',
_18
_18
/**
_18
* Description of the Warning.
_18
*/
_18
description: 'Received an error when attempting to connect to Insights gateway',
_18
_18
/**
_18
* Optional RTCWarning data coming from Connection.on('warning')
_18
* See https://www.twilio.com/docs/voice/sdks/javascript/v1/connection#onwarning-handlerwarningname
_18
*/
_18
rtcWarning: {...}
_18
}


The callsid generated for the test call. This is set when the client has finished connecting to Twilio.

A timestamp in milliseconds of when the test ended. This is set when the test has completed and raised the completed event.

The latest WebRTC sample collected. This is set whenever the connection emits a sample. Please see Connection.on('sample') API for more details.

The report for this test. This is set when the test has completed and raised the completed event.

A timestamp in milliseconds of when the test started. This is set right after calling Device.runPreflight(token, options).

The status of the test. Below are the possible values for this property.

ValueDescription
CompletedThe connection to Twilio has been disconnected and the test call has completed.
ConnectedThe connection to Twilio has been established.
ConnectingConnecting to Twilio has started.
FailedThe test has stopped and failed.

TwiML Apps for PreflightTest

twiml-apps-for-preflighttest page anchor

Please see our example application(link takes you to an external page) if you don't want to setup the required TwiML Apps manually.

Twilio.Device.runPreflight(token, options) requires a Twilio Access Token to initiate the test call. This access token will be passed directly to the Device's constructor and will be used to connect to a TwiML app that you associated with your Twilio Access 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. Below are example TwiML Apps that you can use and some setup instructions.


If PreflightTest.Options.fakeMicInput is set to false, Device.runPreflight(token, options) API requires a token with a TwiML app that can record an audio from a microphone and the ability to play the recorded audio back to the browser. In order to achieve this, we need two TwiML endpoints: one to capture and record the audio, and another one to play the recorded audio.

In this example, we will use TwiML Bins for our TwiML app. Start by going to the TwiML Bin(link takes you to an external page) page in the Twilio Console.

Create a new TwiML Bin with the plus button on that screen and use Playback as the friendly name. Then use the following template under the TwiML section.


_10
<?xml version="1.0" encoding="UTF-8"?>
_10
_10
<Response>
_10
<Say>You said:</Say>
_10
<Play loop="1">{{RecordingUrl}}</Play>
_10
<Say>Now waiting for a few seconds to gather audio performance metrics.</Say>
_10
<Pause length="3"/>
_10
<Say>Hanging up now.</Say>
_10
</Response>

Using the TwiML Bin(link takes you to an external page) page, let's create another TwiML Bin by clicking the plus button on that screen and use Record as the friendly name. Then replace the action url in the following template with your TwiML Bin's Playback url that you created previously. Let's use this template under the TwiML section.


_10
<?xml version="1.0" encoding="UTF-8"?>
_10
_10
<Response>
_10
<Say>Record a message in 3, 2, 1</Say>
_10
<Record maxLength="5" action="https://my-record-twiml-url"></Record>
_10
<Say>Did not detect a message to record</Say>
_10
</Response>

Now that we have created our TwiML Bins, let's create our TwiML app by going to the TwiML Apps(link takes you to an external page) page. Click the plus button on that screen and enter a friendly name that you prefer. Under Voice request url, enter the TwiML Bin's Record url that you created in the previous section, and then click the Create button.

On that same page, open the TwiML app that you just created by clicking on it and make note of the SID. You can now use this TwiML app to generate your token when calling Device.runPreflight(token, options) API.


If PreflightTest.Options.fakeMicInput is set to true, Device.runPreflight(token, options) API requires a token with a single TwiML app that can capture and play an audio. Following the previous steps, create a TwiML Bin and a TwiML App using the following template.


_10
<?xml version="1.0" encoding="UTF-8"?>
_10
_10
<Response>
_10
<Echo/>
_10
</Response>


Rate this page: