Voice JavaScript SDK: Twilio.PreflightTest

You will need an Access Token to initiate the test call. The Access Token will be associated with a TwiML application.

You likely already have a TwiML app with a Voice Request URL configured to send an HTTP POST request to an endpoint on your project's backend.

For the best test results, the endpoint with which you've configured your TwiML App should be able to record audio from a microphone and play it back to the browser.

Your backend application can be modified to handle this behavior, but you can also set up a new TwiML Application configured with TwiML bins specifically for PreflightTests. See the TwiML Apps for PreflightTest section below for more information.

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.

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.

Passes the report object to the completed event handler.

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

See the Report section below to view an example of this report.

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

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.

Passes a TwilioError object or a DOMError object to the failed event handler.

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

Raised when the test Call gets a WebRTC sample object. The event is published every second.

Passes the RTCSample object to the sample event handler.

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

Raised whenever the test Call encounters a warning.

Passes the name of the warning (string) and the Warning object to the warning event handler.

preflightTest.on('warning', handler(name, warning));

The Call SID for the test call. This is set when the test Device instance 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 Call emits a sample.

Returns an RTCSample object or undefined.

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

See the Report section below for more information on the report object.

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.

Below is an example report returned to the completed event handler or accessed via preflightTest.report.

1
{
2
    "callSid": "CAa6a7a187a9cba2714d6fdccf472cc7b1",
3
    "edge": "ashburn",
4
    "iceCandidateStats": [...],
5
    "networkTiming": {
6
        "signaling": {
7
            "start": 1628271850137,
8
            "end": 1628271850958,
9
            "duration": 821
10
        },
11
        "dtls": {
12
            "start": 1628271851032,
13
            "end": 1628271851192,
14
            "duration": 160
15
        },
16
        "ice": {
17
            "start": 1628271850956,
18
            "end": 1628271851032,
19
            "duration": 76
20
        },
21
        "peerConnection": {
22
            "start": 1628271850965,
23
            "end": 1628271851193,
24
            "duration": 228
25
        }
26
    },
27
    "samples": [
28
        {
29
            "audioInputLevel": 10999,
30
            "audioOutputLevel": 1725,
31
            "bytesReceived": 2880,
32
            "bytesSent": 6080,
33
            "codecName": "PCMU",
34
            "jitter": 0,
35
            "mos": null,
36
            "packetsLost": 0,
37
            "packetsLostFraction": 0,
38
            "packetsReceived": 18,
39
            "packetsSent": 38,
40
            "rtt": 66,
41
            "timestamp": 1628271851961.724,
42
            "totals": {
43
                "bytesReceived": 2880,
44
                "bytesSent": 6080,
45
                "packetsLost": 0,
46
                "packetsLostFraction": 0,
47
                "packetsReceived": 18,
48
                "packetsSent": 38
49
            }
50
        }
51
    ],
52
    "selectedEdge": "roaming",
53
    "stats": {
54
        "jitter": {
55
            "average": 1.2273,
56
            "max": 3,
57
            "min": 0
58
        },
59
        "mos": {
60
            "average": 4.4,
61
            "max": 4.406226172226452,
62
            "min": 4.390523592170177
63
        },
64
        "rtt": {
65
            "average": 69.045,
66
            "max": 84,
67
            "min": 59
68
        }
69
    },
70
    "testTiming": {
71
        "start": 1628271849623,
72
        "end": 1628271874932,
73
        "duration": 25309
74
    },
75
    "totals": {
76
        "bytesReceived": 109280,
77
        "bytesSent": 182080,
78
        "packetsLost": 0,
79
        "packetsLostFraction": 0,
80
        "packetsReceived": 683,
81
        "packetsSent": 1138
82
    },
83
    "warnings": [
84
        {
85
            "name": "low-bytes-received",
86
            "description": "Received an RTCWarning. See .rtcWarning for the RTCWarning",
87
            "rtcWarning": {
88
                "values": [
89
                    0,
90
                    0,
91
                    0
92
                ],
93
                "samples": [
94
                    {
95
                        "audioInputLevel": 11718,
96
                        "audioOutputLevel": 0,
97
                        "bytesReceived": 0,
98
                        "bytesSent": 8000,
99
                        "codecName": "PCMU",
100
                        "jitter": 1,
101
                        "mos": 4.404255907879351,
102
                        "packetsLost": 0,
103
                        "packetsLostFraction": 0,
104
                        "packetsReceived": 0,
105
                        "packetsSent": 50,
106
                        "rtt": 61,
107
                        "timestamp": 1628271856961.176,
108
                        "totals": {
109
                            "bytesReceived": 29920,
110
                            "bytesSent": 46080,
111
                            "packetsLost": 0,
112
                            "packetsLostFraction": 0,
113
                            "packetsReceived": 187,
114
                            "packetsSent": 288
115
                        }
116
                    },
117
                    {
118
                        "audioInputLevel": 11261,
119
                        "audioOutputLevel": 0,
120
                        "bytesReceived": 0,
121
                        "bytesSent": 8000,
122
                        "codecName": "PCMU",
123
                        "jitter": 1,
124
                        "mos": 4.404255907879351,
125
                        "packetsLost": 0,
126
                        "packetsLostFraction": 0,
127
                        "packetsReceived": 0,
128
                        "packetsSent": 50,
129
                        "rtt": 61,
130
                        "timestamp": 1628271857960.764,
131
                        "totals": {
132
                            "bytesReceived": 29920,
133
                            "bytesSent": 54080,
134
                            "packetsLost": 0,
135
                            "packetsLostFraction": 0,
136
                            "packetsReceived": 187,
137
                            "packetsSent": 338
138
                        }
139
                    },
140
                ],
141
                "name": "bytesReceived",
142
                "threshold": {
143
                    "name": "min",
144
                    "value": 1
145
                }
146
            }
147
        }
148
    ],
149
    "selectedIceCandidatePairStats": {
150
        "localCandidate": {
151
            "id": "RTCIceCandidate_XXXXXXXX",
152
            "timestamp": 1628271851961.724,
153
            "type": "local-candidate",
154
            "transportId": "RTCTransport_0_1",
155
            "isRemote": false,
156
            "networkType": "wifi",
157
            "ip": "xx.xx.x.xx",
158
            "address": "xx.xx.x.xx",
159
            "port": 44444,
160
            "protocol": "udp",
161
            "candidateType": "prflx",
162
            "priority": 1853759231
163
        },
164
        "remoteCandidate": {
165
            "id": "RTCIceCandidate_XXXXXXXX",
166
            "timestamp": 1628271851961.724,
167
            "type": "remote-candidate",
168
            "transportId": "RTCTransport_0_1",
169
            "isRemote": true,
170
            "ip": "xx.xxx.xxx.xxx",
171
            "address": "xx.xxx.xxx.xxx",
172
            "port": 11111,
173
            "protocol": "udp",
174
            "candidateType": "host",
175
            "priority": 2130706431
176
        }
177
    },
178
    "isTurnRequired": false,
179
    "callQuality": "excellent"
180
}

Report Properties

Property: callSid

Description:

The Call SID for the test call.

Property: edge

Description:

The Edge location that the test call was connected to

Property: iceCandidateStats

Description:

An array of WebRTC stats for the ICE candidates gathered when connecting to media. Each item is an RTCIceCandidateStats object which provides information related to an ICE candidate.

Property: networkTiming

Description:

Measurements for establishing DTLS connection. Properties:

• dtls: This is measured from RTCDtlsTransport connecting to connected state.

  • See the documentation for RTCDtlsTransport state for more information.

• ice: Measurements for establishing ICE connection.

  • This is measured from ICE connection checking to connected state. See the documentation for RTCPeerConnection.iceConnectionState for more information.

• peerConnection: Measurements for establishing a Peer Connection

  • This is measured from PeerConnection connecting to connected state. See the documentation for RTCPeerConnection.connectionState for more information.

• signaling: Measurements for establishing Signaling connection.

  • This is measured from initiating a connection using device.connect() up to when RTCPeerConnection.signalingState transitions to stable state. See the documentation for RTCPeerConnection.signalingState for more information.

Property: samples

Description:

WebRTC samples collected during the test. See the object format on the RTCSample Interface reference page.

Property: selectedEdge

Description:

The edge passed to Device.runPreflight

Property: stats

Description:

RTC-related stats that are extracted from WebRTC samples. This information includes maximum, minimum, and average values calculated for each statistic.

Property: testTiming

Description:

Timing measurement related to the test. Includes millisecond timestamps and duration.

Property: totals

Description:

Calculated totals in RTC statistics samples.

Property: warnings

Description:

PreflightTest.Warnings detected during the test

Property: selectedIceCandidatePairStats

Description:

A WebRTC stats object for the ICE candidate pair used to connect to media, if candidates were selected. Each item is an RTCIceCandidatePairStats object which provides information related to an ICE candidate.

Property: isTurnRequired

Description:

Whether a TURN server is required to connect to media. This is dependent on the selected ICE candidates, and will be true if either is of type "relay", false if both are of another type, or undefined if there are no selected ICE candidates. See PreflightTest.Options.iceServers for more details.

Property: callQuality

Description:

The quality of the call, determined by the MOS (Mean Opinion Score) of the audio stream. Possible values include:

• Excellent - If the average mos is over 4.2
• Great - If the average mos is between 4.1 and 4.2 both inclusive
• Good - If the average mos is between 3.7 and 4.0 both inclusive
• Fair - If the average mos is between 3.1 and 3.6 both inclusive
• Degraded - If the average mos is 3.0 or below

Please see our example application if you don't want to set up 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 page in the Twilio Console.

Playback TwiML Bin

Create a new TwiML Bin with the plus button on that screen and use "Playback" as the friendly name.

Then use the following TwiML under the TwiML section.

1
<?xml version="1.0" encoding="UTF-8"?>
2

3
<Response>
4
  <Say>You said:</Say>
5
  <Play loop="1">{{RecordingUrl}}</Play>
6
  <Say>Now waiting for a few seconds to gather audio performance metrics.</Say>
7
  <Pause length="3"/>
8
  <Say>Hanging up now.</Say>
9
</Response>

Record TwiML Bin

Using the TwiML Bin 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 "Playback" TwiML Bin's URL that you created previously:

1
<?xml version="1.0" encoding="UTF-8"?>
2

3
<Response>
4
  <Say>Record a message in 3, 2, 1</Say>
5
  <Record maxLength="5" action="https://my-record-twimlBin-url"></Record>
6
  <Say>Did not detect a message to record</Say>
7
</Response>

Creating the TwiML Application

Now that we have created our TwiML Bins, let's create our TwiML app by going to the TwiML Apps page.

1. Click the plus button on that screen
2. Enter a friendly name for the application like "PreflightTest".
3. Under Voice request URL, enter your Record TwiML Bin's URL that you created in the previous section, and then click the Create button.
4. 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 Access Token when calling Device.runPreflight(token, options).

If PreflightTest.Options.fakeMicInput is set to true, Device.runPreflight(token, options) API requires an Access Token with a TwiML app that can capture and play audio.

Following the previous steps, create a TwiML Bin using the following TwiML and create a new TwiML Application pointed to that TwiML Bin's URL.

1
<?xml version="1.0" encoding="UTF-8"?>
2

3
<Response>
4
  <Echo/>
5
</Response>