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

Details: Voice Insights SDK Events


Voice Insights enables you to see key events that occur in the lifecycle of a Twilio Voice SDK call. The event log provides events on any state change transitions that occur during a call, warnings seen on deteriorating network quality or audio equipment malfunction, and the events raised when the feedback submitted by the end user. Event log also contains errors seen on connection failures. Connection errors occur when the Twilio SDK fails to connect with Twilio servers. These failures can occur because of severe network degradation or due to a firewall.

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


ERROR and WARNING events

error-and-warning-events page anchor

The following events are logged to the Voice Insights system and are also raised as error or warning events in the SDK.

Network warnings

network-warnings page anchor

The following events are raised when Twilio SDKs detect deteriorating network conditions on the stream received at the SDK sensors from the Twilio media gateway. 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 Nameevent Leveltrigger conditionDescription
high-rttWARNINGRound Trip Time (RTT) > 400 ms for 3 out of last 5 samplesRound-trip-time (RTT) is the measure of latency in the network. Higher latency can result in perceptible delays in audio.
low-mosWARNINGMean Opinion Score (MOS) < 3.5 for 3 out of last 5 samplesMean Opinion Score (MOS) is a measure of the overall network conditions that affect call quality.
high-jitterWARNINGJitter > 30 ms for 3 out of last 5 samplesJitter is the measure of variability at which packets arrive at the SDK sensors. High jitter can result in audio quality problems on the call, such as crackling and choppy audio.
high-packet-lossWARNINGPacket loss > 1% in 3 out of last 5 samplesPacket loss is measured as the percentage of packets that were sent but not received at the SDK sensors. High packet loss can result in choppy audio or a dropped call.
high-packets-lost-fractionWARNINGPacket loss > 3% in 7 out of last 10 samplesA more severe event than merely high-packet-loss. Packet loss can result in choppy audio or a dropped call (Android/iOS SDKs only).
low-bytes-receivedWARNINGBytes received = 0 for three consecutive secondsThe SDK sensors detect no bytes being received at the SDK (JS SDK only).
low-bytes-sentWARNINGBytes sent = 0 for three consecutive secondsThe SDK sensors detect no bytes being sent from the SDK (JS SDK only).
ice-connectivity-lostWARNINGICE transitions to disconnected stateThe previously selected ICE connection was lost and renegotiation will be required. (JS SDK only).

The following events are raised whenever Twilio SDKs detect that the audio level has stayed constant for an unexpected duration. As the participants interact on the call, audio levels vary. Although these events could indicate a problem, constant audio 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. These warning level events are cleared on any fluctuation in audio levels.

event Nameevent Leveltrigger condition
constant-audio-input-levelWARNINGAudio input level from the microphone is unchanged for 20 seconds. JS SDK 1.13.0 and later: The most recent ten seconds of volume values are recorded and then analyzed. If the standard deviation of these samples is less than 1% of the maximum audio value, then the warning is raised.
constant-audio-output-levelWARNINGAudio output level from the speakers/headset is unchanged for 20 seconds. JS SDK 1.13.0 and later: The most recent ten seconds of volume values are recorded and then analyzed. If the standard deviation of these samples is less than 1% of the maximum audio value, then the warning is raised.

Audio errors are also fired when speaker and ringtone devices fail to set (JS SDK only).

event Nameevent Leveltrigger condition
ringtone-devices-set-failedERROROutput selection is not supported by the browser, a specified deviceId wasn't found, or no deviceIds were specified
speaker-devices-set-failedERROROutput selection is not supported by the browser, a specified deviceId wasn't found, or no deviceIds were specified
event Nameevent Leveltrigger condition
listening-errorWARNINGRaised when an attempt to listen for cancellation has failed (Android/iOS only)
errorERRORA connection error occurred. Errors can occur due to bad network conditions or due to setup failures.

Peer Connection warnings

peer-connection-warnings page anchor

The following events are logged as part of the pc-connection-state group.

event Nameevent Leveltrigger condition
failedWARNINGRaised when one or more of the ICE transports on the connection is in the "failed" state.

ICE Gathering State warnings

ice-gathering-state-warnings page anchor

These events are logged as part of the ice-gathering-state group.

event Nameevent Leveltrigger condition
noneWARNINGRaised when no ICE candidates are gathered.
timeoutWARNINGRaised when ICE candidate gathering times out.

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(link takes you to an external page):

event Nameevent Leveltrigger condition
failedERRORThe 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.

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 Nameevent Leveltrigger condition
failedERRORTwilio Voice SDK 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.
deniedERRORThe user denied permission to access microphone/speakers, and as a result connection could not be established.
event Nameevent Leveltrigger condition
unsupported-cancel-message-errorERRORRaised when a "cancel" push notification is processed by the SDK. The version of the SDK does not support "cancel" push notifications.
registration-errorERRORRaised when registration fails.
unregistration-errorERRORRaised when unregistration fails.
unregistration-registration-errorERRORIn order to unregister, a registration needs to have been performed. Attempts to unregister a client instance that is not registered will result in this error.

INFO and DEBUG events

other page anchor

The following events are logged to the Voice Insights system, but are not raised as warning events in the Twilio SDKs.

Network warning cleared events

network-warning-cleared page anchor

When Twilio SDKs detect that network conditions are back to normal, these warnings are cleared. The warning-cleared events belong to the network-quality-warning-cleared group.

event Nameevent Leveltrigger condition
high-rttINFORound Trip Time (RTT) < 400 ms for 3 out of last 5 samples
low-mosINFOMean Opinion Score (MOS) > 3.5 for 3 out of last 5 samples
high-jitterINFOJitter < 30 ms for 3 out of last 5 samples
high-packet-lossINFOpacket loss < 3% in 7 out of last 10 samples

Audio warning cleared events

audio-warning-cleared page anchor

These belong to the group audio-level-warning-cleared.

event Nameevent Leveltrigger condition
constant-audio-input-levelINFORaised when audio input level starts varying again after a warning was raised
constant-audio-output-levelINFORaised when audio output level starts varying again after a warning was raised

Audio events are fired when speaker and ringtone devices are set and when a device change is detected (JS SDK only).

event Nameevent Leveltrigger condition
speaker-devices-setINFOspeakerDevices set via Twilio.AudioOutputCollection
ringtone-devices-setINFOringtoneDevices set via Twilio.AudioOutputCollection
device-changeINFOFired 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 user 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.

ICE-Connection-State events

ice page anchor

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(link takes you to an external page):

event Nameevent LevelDescription
checkingDEBUGThe 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.
connectedDEBUGA 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.
closedDEBUGThe ICE agent for this RTCPeerConnection has shut down and is no longer handling requests.
completedDEBUGThe ICE agent has finished gathering candidates, has checked all pairs against one another, and has found a connection for all components.
disconnectedDEBUGChecks 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.

Signaling-State events

signaling page anchor

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

event Nameevent LevelDescription
stableDEBUGThere 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.
closedDEBUGThe connection is closed.
have-remote-offerDEBUGThe 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-offerDEBUGThe 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.
have-remote-pranswerINFOAndroid/iOS SDK only

More information on Signaling events is available here(link takes you to an external page).

Connection events

connection page anchor

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

event Nameevent LevelDescription
disconnected-by-localINFOThe connection was disconnected by the local participant.
incomingINFOTwilio Voice SDK received an incoming connection.
accepted-by-localINFOThe connection was accepted by the client app.
accepted-by-remoteINFOThe connection was accepted by the remote participant being called.
disconnected-by-remoteINFOThe remote participant initiated the disconnect.
ignored-by-localINFOThe incoming connection was ignored by the client.
unmutedINFOThe connection was unmuted.
mutedINFOThe connection was muted.
rejected-by-localINFOAn incoming connection was rejected by the local participant.
connectedINFO(Android and iOS SDK only).
outgoingINFO(Android and iOS SDK only).
ringingINFOIndicates the incoming call is ringing (Android and iOS SDK only).
disconnect-calledINFO(Android and iOS SDK only).
outgoing-ringingINFOIndicates the outbound call is ringing.
listenINFORaised when an attempt to listen for cancellations is made (Android and iOS SDK only).
listeningINFORaised when an attempt to listen for cancellations has succeeded(Android and iOS SDK only).
cancelINFORaised when a cancellation has been reported (Android and iOS SDK only).
reconnectingINFORaised when media connection fails and automatic reconnection has been started by issuing ICE Restarts.
reconnectedINFORaised when media connection has been restored which is detected when media starts flowing.
holdINFOIndicates the call has been put on hold (Android and iOS SDK only).
unholdINFOIndicates the call has been taken off hold (Android and iOS SDK only).

Peer Connection events

peer-connection page anchor

The following events are logged as part of the pc-connection-state group. They indicate key events that describe the state of the peer connection between the SDK and Twilio's WebRTC gateway. (JS SDK Only)

event Nameevent LevelDescription
connectingDEBUGOne or more of the ICE transports are currently in the process of establishing a connection; that is, their RTCIceConnectionState is either "checking" or "connected", and no transports are in the "failed" state.
connectedDEBUGEvery ICE transport used by the connection is either in use (state "connected" or "completed") or is closed (state "closed"); in addition, at least one transport is either "connected" or "completed".
disconnectedDEBUGAt least one of the ICE transports for the connection is in the "disconnected" state and none of the other transports are in the state "failed", "connecting", or "checking".
newDEBUGAt least one of the connection's ICE transports (RTCIceTransports or RTCDtlsTransports) are in the "new" state, and none of them are in one of the following states: "connecting", "checking", "failed", or "disconnected", or all of the connection's transports are in the "closed" state.
closedDEBUGThe RTCPeerConnection is closed.

ICE Candidate Events

ice-candidate page anchor

These events are logged as part of the ice-candidate group.

event Nameevent LevelDescription
ice-candidateDEBUGRaised during ICE gathering process when an ICE candidate is identified.
selected-ice-candidate-pairDEBUGShows the transport protocol and ICE candidate type(link takes you to an external page) for both local and remote participants.

ICE Gathering State Events

ice-gathering page anchor

The events below are logged as part of the ice-gathering-state group.

event Nameevent LevelDescription
newDEBUGIndicates the peer connection was just created and hasn't done any networking yet.
gatheringDEBUGIndicates the ICE agent is in the process of gathering candidates for the connection.
completeDEBUGRaised when the ICE agent has finished gathering candidates. If something happens that requires collecting new candidates, such as a new interface being added or the addition of a new ICE server, the state will revert to gathering to gather those candidates.

ICE Connection State Events

ice-connection page anchor

The following events are logged as part of the ice-connection-state group.

event Nameevent LevelDescription
connectingDEBUGThe ICE agent is connecting to the remote candidate.
newDEBUGThe ICE agent is gathering addresses or is waiting to be given remote candidates.
gatheringDEBUGThe ICE agent is gathering candidates.
completedDEBUGThe ICE agent has finished gathering candidates, has checked all pairs against one another, and has found a connection for all components.
noneDEBUGNo ICE candidates returned.
timeoutDEBUGThe ICE connection has timed out.
checkingDEBUGThe 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.
disconnectedDEBUGChecks 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.
closedDEBUGThe ICE agent for this RTCPeerConnection has shut down and is no longer handling requests.
connectedDEBUGA 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.

User Media events

user-media page anchor

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 Nameevent LevelDescription
succeededINFOTwilio Voice SDK successfully got access to user's media devices. This is perquisite for establishing a connection.

Settings events

settings page anchor
event Nameevent LevelDescription
codecINFORaised when the codec has been selected

Feedback events

feedback page anchor

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 Nameevent LevelDescription
receivedINFOThis 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-noneINFOThis 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.

Registration events (Android & iOS SDKs only)

registration page anchor
event Nameevent LevelDescription
registrationINFORaised when the client identity is registered.
unregistrationINFORaised when the client identity is unregistered.

Network Information events (JS SDK only)

network-information page anchor
event Nameevent LevelDescription
network-changeINFOExperimental feature: https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation(link takes you to an external page)

Rate this page: