Register by 10/16 for $250 off the on-site price.

Insights Events Reference

Voice Insights enables you to see key events that occur in the lifecycle of a Twilio Client call.

Many events are also raised as events in the twilio.js library (v1.4+), allowing you to alert your end-users on changing network/device conditions.

The event reference describes each event to give you visibility into the call lifecycle.

Warning events

The following events are logged to the Voice Insights system and are also raised as warning events in the twilio.js library.

Network Warnings

The following events are raised when twilio.js detects deteriorating network conditions. These events belong to the network-quality-warning-raised group.

You can implement handlers for these events by listening for #warning events to show visual indicators that alert the end user to a problem.

event Name event Level trigger condition Description
high-rtt WARNING Round Trip Time (RTT) > 400 ms for 3 out of last 5 samples Round-trip-time (RTT) is the measure of latency in the network. Higher latency can result in perceptible delays in audio.
low-mos WARNING Mean Opinion Score (MOS) < 3.5 for 3 out of last 5 samples Mean Opinion Score (MOS) is a measure of the overall network conditions that affect call quality.
high-jitter WARNING Jitter > 30 ms for 3 out of last 5 samples Jitter is the measure of variability at which packets arrive at the endpoint. High jitter can result in audio quality problems on the call, such as crackling and choppy audio.
high-packet-loss WARNING packet loss > 1% in 3 out of last 5 samples Packet loss is measured as the percentage of packets that were sent but not received at the endpoint. High packet loss can result in choppy audio or a dropped call.

When twilio.js detects that network conditions are back to normal, these warnings are cleared. The warning-cleared events belong to the network-quality-warning-cleared group.

event Name event Level trigger condition
high-rtt INFO Round Trip Time (RTT) < 400 ms for 3 out of last 5 samples
low-mos INFO Mean Opinion Score (MOS) > 3.5 for 3 out of last 5 samples
high-jitter INFO Jitter < 30 ms for 3 out of last 5 samples
high-packet-loss INFO packet loss < 1% in 3 out of last 5 samples

Audio level events

The following events are raised whenever twilio.js detects that the audio input or output level has stayed constant for an unexpected duration. As the participants interact on the call, audio input and output levels vary. Although these events could indicate a problem, constant audio input/output levels could occur when one of the participants has muted their microphone using a hardware mute.

You might find it useful to ask the user if they've mistakenly muted their microphone when these events are raised for an extended period of time.

You can implement handlers for these events by listening for #warning events to show visual indicators that alert the end user to a problem.

The following warning events belong to the audio-level-warning-raised group. These are also emitted by the SDK through the event emitter.

event Name event Level trigger condition
constant-audio-input-level WARNING Audio input level is unchanged for 20 seconds
constant-audio-output-level WARNING Audio output level is unchanged for 20 seconds

These warning level events are cleared on any fluctuation in audio levels. These belong to the group audio-level-warning-cleared.

event Name event Level trigger condition
constant-audio-input-level INFO Raised when audio input level starts varying again after a warning was raised.
constant-audio-output-level INFO Raised when audio output level is varying again after a warning was raised.

Other events

The following events are logged to the Voice Insights system, but are not raised as warning events in the twilio.js library.

ICE-Connection-State events

The following events belong to the group ice-connection-state. These are the standard RTCPeerConnection.iceConnection state events as described below. More information on ICE events is available here:

event Name event Level Description
checking DEBUG The ICE agent has been given one or more remote candidates and is checking pairs of local and remote candidates against one another to try to find a compatible match, but has not yet found a pair which will allow the peer connection to be made. It's possible that gathering of candidates is also still underway.
connected DEBUG A usable pairing of local and remote candidates has been found for all components of the connection, and the connection has been established. It's possible that gathering is still underway, and it's also possible that the ICE agent is still checking candidates against one another looking for a better connection to use.
closed DEBUG The ICE agent for this RTCPeerConnection has shut down and is no longer handling requests.
completed DEBUG The ICE agent has finished gathering candidates, has checked all pairs against one another, and has found a connection for all components.
disconnected DEBUG Checks to ensure that components are still connected failed for at least one component of the RTCPeerConnection. This is a less stringent test than failed and may trigger intermittently and resolve just as spontaneously on less reliable networks, or during temporary disconnections. When the problem resolves, the connection may return to the connected state.
failed ERROR The ICE candidate has checked all candidates pairs against one another and has failed to find compatible matches for all components of the connection. It is, however, possible that the ICE agent did find compatible connections for some components.

Signaling-State events

The following events belong to the signaling-state group. These are the standard RTCPeerConnection.signalingState events as described below.

event Name event Level Description
stable DEBUG There is no ongoing exchange of offer and answer underway. This may mean that the RTCPeerConnection object is new, in which case both the localDescription and remoteDescription are null; it may also mean that negotiation is complete and a connection has been established.
closed DEBUG The connection is closed.
have-remote-offer DEBUG The remote peer has created an offer and used the signaling server to deliver it to the local peer, which has set the offer as the remote description by calling RTCPeerConnection.setRemoteDescription().
have-local-offer DEBUG The local peer has called RTCPeerConnection.setLocalDescription(), passing in SDP representing an offer (usually created by calling RTCPeerConnection.createOffer()), and the offer has been applied successfully.

More information on Signaling events is available here.

Connection events

The following events belong to the connection group. They are logs of the key events that describe the state of the connection.

event Name event Level Description
disconnected-by-local INFO The connection was disconnected by the local participant.
incoming INFO Twilio Client received an incoming connection.
accepted-by-local INFO The connection was accepted by the client app.
accepted-by-remote INFO The connection was accepted by the remote participant being called.
disconnected-by-remote INFO The remote participant initiated the disconnect.
ignored-by-local INFO The incoming connection was ignored by the client.
unmuted INFO The connection was unmuted.
muted INFO The connection was muted.
rejected-by-local INFO An incoming connection was rejected by the local participant.
error ERROR A connection error occurred. Errors can occur due to bad network conditions or due to setup failures.

User Media events

The following events belong to the get-user-media group. These events indicate whether twilio.js was able to access the user's audio microphone.

event Name event Level Description
succeeded INFO Twilio client successfully got access to user's media devices. This is perquisite for establishing a connection.
failed ERROR Twilio client failed to get access to user's media devices. This event is logged if the microphone was not accessible due to other errors on the user's device.
denied ERROR The user denied permission to access microphone/speakers, and as a result connection could not be established.

Feedback events

Twilio.js allows users to rate the quality of each call through its postFeedback API. Once feedback has been submitted, you can visualize and analyze the results through the Voice Insights dashboards.

Feedback events belong to the group feedback

event Name event Level Description
received INFO This event is logged when you post feedback to Twilio using the postFeedback API. The event contains the issue-name and the quality-score submitted by the user.
received-none INFO This event is logged when you call the postFeedback API without any parameters. The event is used to log the instances where you prompted the user for feedback, but the user declined to submit feedback.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.