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

Preflight API


(warning)

Warning

This documentation is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2026(link takes you to an external page).

We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide(link takes you to an external page) to assist you in minimizing any service disruption.

The Twilio Video JavaScript Preflight API(link takes you to an external page) provides functions for testing connectivity to the Twilio Cloud. The API can identify signaling and media connectivity issues and provide a report at the end of the test. You can use the Preflight API in your Twilio Video applications to detect issues before a Participant joins a Video Room or as part of a troubleshooting page.

To check connectivity, the Preflight API creates two peer connections from the local user to Twilio's Signaling and TURN servers. It publishes synthetic audio and video tracks from one of those connections and ensures that the other connection receives the media on those tracks. After successfully verifying connectivity, it generates a report with information about the connection.

(information)

Info

The Preflight API does not test users' bandwidth limitations. If you would like to test limitations in clients' available bandwidth, you should use the testMediaConnectionBitrate method from the RTC Diagnostics SDK(link takes you to an external page).


Access the Preflight API

access-the-preflight-api page anchor

The Preflight API is included with the Twilio Video JavaScript SDK in versions 2.16.0 and above. Versions 2.16.0 through 2.19.1 of the JavaScript SDK contain beta version of the Preflight API. Version 2.20.0 and above of the JavaScript SDK contain the generally available Preflight API, which is no longer in beta.

You can include the JavaScript SDK in your application either by installing it with Node Package Manager(link takes you to an external page) (npm) or using the Twilio CDN.

See the list of supported browsers here.

NPM

npm page anchor

Install the Video JavaScript SDK using npm:


_10
npm install --save twilio-video

Then, you can start using the Preflight API in your application (note that the Preflight API is under the name runPreflight):


_10
const { runPreflight } = require('twilio-video');

Script tag

script-tag page anchor

You can also copy twilio-video.min.js from the twilio-video/dist folder after npm installing it and include it directly in your web app using a <script> tag.


_10
<script src="https://my-server-path/twilio-video.min.js"></script>

Using this method, you can access the PreflightTest API like so:


_10
const runPreflight = Twilio.Video.runPreflight;

You can also include the JavaScript SDK in your application from Twilio's CDN:


_10
<script src="https://sdk.twilio.com/js/video/releases/2.20.0/twilio-video.min.js"></script>

(information)

Info

You should make sure you're using the latest Twilio Video JavaScript SDK release. To find the CDN link for the most recent JavaScript SDK release, visit the JavaScript SDK latest release documentation(link takes you to an external page).

Using the CDN, the JavaScript SDK will set a browser global that you can use to reference the Preflight API:


_10
const runPreflight = Twilio.Video.runPreflight;


Below is an example of how to use the Preflight API to start a diagnostic connectivity test and handle events during the test.


_38
// import the Preflight API, which is called `runPreflight`,
_38
// from the Twilio Video JavaScript SDK
_38
const { runPreflight } = require('twilio-video');
_38
_38
// if you are using the Video JavaScript SDK via the Twilio CDN or
_38
// a script tag, you would reference the Preflight API this way:
_38
// const runPreflight = Twilio.Video.runPreflight;
_38
_38
// this assumes you have a function called getAccessToken
_38
// to retrieve an Access Token from your server
_38
const token = getAccessToken();
_38
_38
// run a preflight test, passing in an Access Token with
_38
// a VideoGrant
_38
const preflightTest = runPreflight(token);
_38
_38
// handle preflight test events
_38
_38
// while the test is in progress, the progress event fires
_38
// whenever a particular PreflightProgress step completes
_38
preflightTest.on('progress', (progress) => {
_38
console.log('preflight progress:', progress);
_38
});
_38
_38
// if the test failed, the failed event fires and returns the error
_38
// along with the partial test results it was able to collect
_38
preflightTest.on('failed', (error, report) => {
_38
console.error('preflight error:', error);
_38
console.log('Received partial report:', report);
_38
});
_38
_38
// if the test completed without error, the completed event fires
_38
// and returns the preflight test report
_38
preflightTest.on('completed', (report) => {
_38
console.log("Test completed in " + report.testTiming.duration + " milliseconds.");
_38
console.log(" It took " + report.networkTiming.connect?.duration + " milliseconds to connect");
_38
console.log(" It took " + report.networkTiming.media?.duration + " milliseconds to receive media");
_38
});

Start the diagnostic test

start-the-diagnostic-test page anchor

To start a diagnostic test with the Preflight API, call the runPreflight() method(link takes you to an external page) and pass in an Access Token with a VideoGrant, which allows you to set up test connections to Twilio's servers.

You can optionally pass in other PreflightOptions(link takes you to an external page)when you run the test(link takes you to an external page). The options include setting your preferred signaling region within the Twilio cloud (region; default is gll) and the amount of time to run the test (duration; the default is 10000 ms, or 10 seconds).

The Access Token you pass to the runPreflight must contain a VideoGrant.

Because the Preflight API is connecting to a test Video Room that the Preflight API sets up, any value you pass in for the room and identity fields in the VideoGrant will be ignored during the preflight test. The Access Token you use does require an identity field, but this identity can be any value for the purpose of the test.

Listen for preflight test events

listen-for-preflight-test-events page anchor

After you start running the preflight test with the runPreflight method, the test can generate three types of events. The code example above demonstrates how to listen for each event type.

  • progress : The test is in progress and a PreflightProgress step(link takes you to an external page) in the test completed. This event passes the specific PreflightProgress step that completed.
  • failed : The test failed with an error. This event passes back the error and any partially generated test results.
  • completed : The test completed successfully and you can review the results. This event passes back the completed test report.

Use PreflightProgress steps to track connectivity

use-preflightprogress-steps-to-track-connectivity page anchor

While the Preflight Test is in progress, it will emit ProgressEvents indicating it completed specific connectivity checks. You can use these events to track the test progress and provide additional feedback to end users about their connections.

NameDescription
mediaAcquiredSuccessfully generated synthetic tracks
connectedSuccessfully connected to Twilio's server and obtained TURN credentials
mediaSubscribedThe test connection successfully subscribed to media tracks
mediaStartedMedia flow was detected
dtlsConnectedEstablished DTLS connection. This event will be not be emitted on Safari browsers.
peerConnectionConnectedEstablished a PeerConnection(link takes you to an external page). This event will not be emitted on Firefox browsers.
iceConnectedEstablished an ICE connection

Review the completed test report

review-the-completed-test-report page anchor

The completed event will pass back a report containing the results from the successful test. The report will contain the following fields:

NameDescription
testTimingTime measurements for when the test started and ended (in Epoch time) and how long the test lasted in ms.
networkTimingNetworking timing measurements(link takes you to an external page) captured during the test.
iceCandidateStatsAn array containing the gathered ICE clients for STUN/TURN. Learn more about STUN, TURN, and ICE here.
selectedIceCandidatePairStatsInformation about the ICE candidates that were used for the connection, such as the IP address, port, and protocol used.
progressEventsA list of the ProgressEvents(link takes you to an external page) that occurred during the test.
statsRTC-related statistics(link takes you to an external page) captured during the test. Contains information about the average, minimum, and maximum jitter, round trip time (rtt), and packet loss during the test.

Stop an in-progress test

stop-an-in-progress-test page anchor

You can stop an in-progress test with the stop() method. This will stop the test and emit a failed event, along wtih partial test results that completed up to the point that the test stopped.


Video Diagnostics Application

video-diagnostics-application page anchor

Twilio offers an open-source Video Diagnostics Application(link takes you to an external page) that is built using the Prelight API and the RTC Diagnostics SDK(link takes you to an external page). You can deploy and explore this application to see the different functionality of these diagnostic APIs in action. The application tests participants' device and software setup, connectivity with the Twilio Cloud, and network performance. It provides users feedback about their network quality and device setup, and also includes recommendations for improving their video call quality.


Rate this page: