# Voice Insights Frequently Asked Questions

Learn how Twilio Voice Insights analyzes call quality and performance metrics for voice calls and conferences. This tool provides both high-level cumulative statistics and granular per-interval data to help you diagnose audio issues like [jitter][] and [packet loss][].

To learn more about the API calls and resources used in this guide, see [Related reference documentation][].

## How do Voice Insights and Voice Insights Advanced Features differ?

**Advanced Features log individual metrics and events and return them in the Console, API, and Event Streams**.

* *Voice Insights* provides cumulative statistics on calls.
* *Voice Insights Advanced Features* offers more granular data including:
  * Logging of call events and metrics
  * Viewing the **Metrics** tab in Console which displays the captured metrics and events
  * Accessing events, metrics, and summary records using API and Event Streams

## Do I need Voice Insights Advanced Features?

**Maybe**. Voice Insights analyzes the stream of metrics and events in-flight, calculates the cumulative metrics for the call, and stores those cumulative stats in the **Call Summary**. To capture per-interval metrics and events and access the data through API or Event Streams, turn on **Voice Insights Advanced Features**.

**Voice Insights Advanced Features** provides the following data points:

* What potential issue was detected
* When the issue was detected
* Which stream had the detected issue
* How this issue affects performance
* How long the issue lasted

If you didn't turn on Advanced Features for your account, API requests return in an HTTP `401 Unauthorized` response.

## How does Insights gather data?

Sensors in the Twilio Voice SDKs and on Twilio media gateways gather call metrics and events. These sensors send the data to the Voice Insights platform for analysis and aggregation.

## How can you gather Voice Insights data from a call?

Use Insights for all calls made or placed with:

* Twilio [Voice SDKs for JavaScript][] (v1.3+)
* [Mobile SDKs for Android and iOS][] (v3.0+)
* Programmable [Voice APIs][]
* [Elastic SIP Trunking][]

Earlier versions of the Voice SDK (1.2 and earlier) and mobile SDKs for Android and iOS (2.0 and earlier) receive metrics and events *as-is*. As a result, some metrics might return unexpected or impossible values.

## Why does Voice Insights focus on network metrics over audio quality?

**Communications use network, not voice, infrastructure**. [Public Switched Telephone Network (PSTN)][pstn] only concerns itself with the physical continuity of copper wires between locations. [Voice over IP (VoIP)][voip] services consider *network metrics* and *audio quality* equivalent. Twilio's analysis of hundreds of billions of calls supports the theory that network transport issues contribute most to reports of audio quality degradation for VoIP calls.

In a VoIP telecom deployment, network issues cause audio artifacts:

| Network cause       | Audio artifact               |
| ------------------- | ---------------------------- |
| [packet loss][]     | choppiness                   |
| [jitter][]          | noise, robotic speech        |
| [post-dial delay][] | one-way audio, dropped calls |

Twilio monitors and reports on metrics on these causes. Without visibility into the network infrastructure behavior, quality issues can't be detected, diagnosed, or resolved.

## What audio quality issues can't Voice Insights detect?

**In-stream audio issues that don't relate to jitter or packet loss**. Calls that Twilio records might have evidence of these issues. The most common audio issue, *echo*, comes from an audio feedback loop. A call participant turns their speaker volume or microphone gain up high enough that their microphone picks up its output and returns it to the media stream.

## How does Twilio's silence detection work?

Twilio's media gateways can detect missing [*Real-Time Transport Protocol* (RTP)][rtp] streams or silent streams. Twilio marks these calls as containing silence in the [Call Summary resource][] response and in the **Call Summary** properties in Console. Streams with enough background noise but without speech might not get marked as silent.

## How does Twilio determine "Who Hung Up"?

Twilio checks its external signaling edge and the direction of which party sent the [SIP `BYE` request][bye].

## Why might "Who Hung Up" be unavailable? \[#unavail-who-hung-up]

To determine who hung up, Twilio uses the source of the SIP `BYE` request at its signaling edge. Before SIP can end a call with a `BYE` request, someone must answer a call. If a calls returns `no-answer`, `failed`, or `canceled`, Twilio can't provide who hung up. You may infer that the calling party ended any unanswered call.

Voice SDK calls might miss who hung up for multiple reasons:

* Computer crashes
* Network issues
* The browser being closed or crashing during an in-progress call
* The client object got destroyed before the event could be sent to Twilio Insights
* Any other unexpected behavior that results in Twilio not receiving the final events from the SDK

When viewing Insights data in Console and aggregate reports, these reasons collectively appear as `disconnected by: unknown`.

## Can Twilio detect dropped calls?

**No**. Most calls reported as dropped appear normal to apps and signals.

If you don't know why a call got dropped, ask your user. To capture the subjective user feedback, integrate the Voice SDK Feedback API into your app. To access the submitted feedback, use the Voice Insights [Call Insights Event resource].

To check feedback of non-SDK calls, Twilio provides the [Call Annotation Resource] and **Call Logs** in the [Twilio Console][1c-voice-logs] or [Legacy Console][lc-voice-logs].

If you can't get direct user feedback, the **Voice Insights Call Summary** includes the final SIP response. To locate calls that didn't end as expected, search for any calls that don't return a SIP `200 OK` response.

For Voice SDK calls, check the reason for disconnection. An `unknown` response might return for reasons explained in [why a hang up might not be found](#unavail-who-hung-up).

## Isn't 1% packet loss and 30 ms jitter a little *too* sensitive?

Twilio bases its quality thresholds on [*International Telecommunication Union Telecommunication Standardization Sector*
(ITU-T)][itu-t] standards for VoIP quality. These lean toward sensitivity. To allow detection and mitigation to occur *before* users notice, issues get highlighted at-or-below the edges of perceptibility. To craft your internal threshold for performance, Twilio also provides cumulative metrics in the call **Summary**.

## Why do the Voice SDKs have more sensitive network and audio warnings than the tagging thresholds?

Almost all quality issues for Voice SDK calls arise from local network conditions. These could be misapplied or absent *quality of service* (QoS), asymmetric bandwidth allocations, or bandwidth limitations. Twilio exposes a more sensitive threshold of data for Voice SDK calls so developers can identify and respond to changing quality conditions. By surfacing warnings in your apps and giving prescriptive instructions, the remedies could get applied before your users notice.

## Why is Post-Dial Delay tagging based on a percentile and not a numeric threshold?

Different destinations have different expectations for post-dial delay, and accordingly varying thresholds for acceptable *Post-Dial Delay* (PDD).

**For example**:

* In the US, a PDD greater than six seconds should be escalated to the carrier.
* In South Africa, callers accept a PDD of 10 seconds.\
  Tagging calls to South Africa with PDD greater than six seconds would tag basically *all* the calls in South Africa, reducing the utility of the data to uncover outliers in performance.

## Why wasn't my call HD?

*High-definition* (HD) audio means the call used a wideband codec, either the *Adaptive Multi-Rate Wideband* (AMR-WB) codec, typical of mobile calls, or Opus, typical of Twilio Voice SDK calls. No other codec counts as HD. For a call to connect with an HD codec, the end user's device must:

* Support that codec.
* Connect to Twilio through a carrier, SIP infrastructure, or Voice SDK application configured for that codec.

## Why was this call tagged `downsampled`? \[#downsampled]

The call connected to Twilio's edge with an HD audio codec. However, the longest part of the call connected to a component or another endpoint that didn't support HD. When an existing HD call connects to a component or endpoint that doesn't support HD, Twilio downsamples the HD audio. This ensures the call stays connected.

## What limitations exist for the Insights Dashboard?

To comply with [GDPR](/docs/glossary/gdpr), Twilio stores Voice Insights data only for 30 days. This limits the Dashboard to 30 days worth of data. As only 30 days worth of data remains available, Twilio can only display comparisons for up to 15 days. Twilio limits CSV exports to 2,000 rows.

## How can I address the SIP errors?

This depends on the source of the errors.

### SIP Interface and Elastic SIP trunking calls errors

Compare your local SIP infrastructure logs and [Packet Captures (PCAP)][pcap] with the Twilio public PCAPs in the **Calls** page of the [Twilio Console][1c-voice-insights-calls] ([legacy Console][lc-voice-insights-calls]).

### Voice SDK SIP errors

Voice SDK SIP errors occur due to unexpected app behavior. To understand the cause, turn on debug logging in your apps and reproduce the issue.

### Carrier SIP errors

You can't do anything about SIP errors that originate from the carriers. To try and resolve issues with a specific carrier, contact [Twilio Support][] with the data to get more help.

## Is this data available using REST APIs?

An API is available as part of Voice Insights Advanced Features that provides access to call events, metrics, and summaries.

## How long does Twilio retain data?

Twilio retains Voice Insights data for 30 days after the call.

## Why do Call Logs and Voice Insights Dashboard numbers differ?

* The [**Voice Insight Dashboard**][1c-voice-insights-calls] ([legacy Console][lc-voice-insights-calls]) provides dynamic filtering and search functionality. The top-level aggregations don't operate on values directly but on their hashes, so they return approximate results.
* The [**Call Logs**][1c-voice-logs] ([legacy Console][lc-voice-logs]) use linear counting. This counting has excellent precision on low-cardinality sets, but doesn't provide multi-dimensional searches and top-level filtering like the Dashboard. In practice, Twilio views differences of less than five on sets of calls with about 100,000 results.

## Why don't I see Voice Insights Metrics or Events for my calls?

To view call events and metrics, turn on **Voice Insights Advanced Features**.

1. Go to the **Voice Insights Settings** page:
   * In Twilio Console, go to **Monitor** > **Insights** > **Voice** > [**Settings**][1c-voice-insights-settings].
   * In the legacy Console, go to **Monitor** > **Insights** > **Voice** > [**Settings**][lc-voice-insights-settings].
2. Click **Select**. The **Change to Voice Insights Advanced Features** modal appears.
3. Click **Confirm Change**.

## Why this Voice SDK call missing Insights metrics, events, or summaries?

Causes of missing metrics, events, or summaries include:

* local network configuration blocking publishing to the Insights events gateway
* expired tokens
* publishing delays on the Voice Insights backend

## Why do I see only one day worth of data for Voice Insights advanced features?

Advanced Features collect data only after you activate it on your account. Before you turn on Advanced Features, Voice Insights doesn't collect data on any calls placed nor does it store the per-interval metrics and event stream.

## How does Twilio calculate RTP Latency?

Twilio [RTP][] latency shows the average and max Twilio-internal media stream traversal time in milliseconds. The Voice Insights platform analyzes the timestamps of when RTP packets are received at the ingress of Twilio's media gateway and compares that timestamp against the timestamp of the same packets at the egress on the other media edge.

## What does high latency mean?

If the Twilio-internal RTP time for outbound packets received at the media edge for a call SID exceeds 150ms, Twilio marks a call as high latency.

To view the latency summary, go to the **Calls** page.

* In Twilio Console, go to **Monitor** > **Insights** > **Voice** > [**Calls**][1c-voice-insights-calls].
* In the legacy Console, go to **Monitor** > **Insights** > **Voice** > [**Calls**][lc-voice-insights-calls].

The **Calls** page displays the *received* latency for the provided call SID. Received latency covers how long packets from the media edge for the other side of the call to traverse Twilio's network on the way to the media edge for this call SID. Twilio marks the *received* call and not the *sending* call. The received call predominantly experiences the latency effects.

## What sources contribute to Twilio internal RTP traversal time?

**Calls with participants spread across distant geographic locations**. Calls placed using a conference call flow include a small [jitter buffer][]. This buffer can result in an increased probability of conference calls being marked as having high latency. High jitter from Voice SDK participants can increase the jitter buffer and delay playout of their media to the other participants in the conference.

```mermaid {title="Twilio Audio Latency Metrics"}
---
title: Conference call network flow
---
flowchart LR
  A((App))
  subgraph Twilio Infrastructure
      B[Client<br/>Edge]
      C(((Conference<br/>Mixer)))
      D[Carrier<br/>Edge]
  end
  E((PSTN))

  A e1@==>|inbound| B e2@==>|inbound| C e3@==>|outbound| D e4@==>|outbound| E
  E e5@==>|outbound| D e6@==>|outbound| C e7@==>|inbound| B e8@==>|inbound| A

  %% Styling animated paths
  e1@{ animate: true, curve: linear }
  e2@{ animate: true, curve: linear }
  e3@{ animate: true, curve: linear }
  e4@{ animate: true, curve: linear }
  e5@{ animate: true, curve: linear }
  e6@{ animate: true, curve: linear }
  e7@{ animate: true, curve: linear }
  e8@{ animate: true, curve: linear }

  %% Define style for flowchart
  classDef ends fill:#F22F47,stroke:#121C1D,stroke-width:2px,color:#fff
  classDef twilio fill:#F22F47,stroke:#fff,stroke-width:2px,color:#fff
  classDef edges fill:#51A9E3,stroke:#62BAF4,stroke-width:2px,color:#000
  classDef empty fill:#fff,stroke:#fff,color:#fff

  %% Apply styles for flowchart
  class B,D edges
  class A,E ends
  class C twilio
  class F,G,H edges
```

To mitigate internal RTP traversal time impact, optimize the region selections for Voice SDK instances and conferences. If large distances separate your users, they experience some degree of Twilio-internal latency.

## How do high round trip time, high latency, and participant latency differ?

```mermaid
---
title: Where latency occurs in the infrastructure
---
%%{init: { 'sequence': {'mirrorActors': false} } }%%
sequenceDiagram
    participant sdk as sdk_edge
    participant ie1 as client_edge
    participant CM as Conference Mixer
    participant de1 as carrier_edge

    sdk-->>+ie1: inbound
    ie1-->>+CM: inbound
    CM-->>-ie1: outbound
    ie1-->>-sdk: outbound
    PSTN-->>+de1: inbound
    de1-->>+CM: inbound
    CM-->>-de1: outbound
    de1-->>-PSTN: outbound
    Note over sdk,ie1: sdk.metrics.rtt
    Note over ie1,de1: edge.metrics.latency
    Note over ie1,CM: participantA.metrics.inbound.latency
    Note over CM,de1: participantB.metrics.inbound.latency
```

These terms differ in where they occur and who they impact.

| Metric                     | Trigger Threshold                       | Scope                                                        |
| -------------------------- | --------------------------------------- | ------------------------------------------------------------ |
| High Round Trip Time (RTT) | >400 ms in [3 of last 5 samples](#3of5) | External latency (Twilio gateway to Voice SDK app)           |
| High Latency               | Avg internal traversal >150 ms          | Internal latency (Twilio media edge ingress to egress)       |
| Participant Latency        | Continuous                              | Bidirectional delay between participant and conference mixer |

## What's a *sample* in the context of "packet loss > 1% in 3 out of last 5 samples"? \[#3of5]

* For Voice SDK calls, Twilio samples each second.
* For Carrier and SIP calls, Twilio samples the cumulative stats for the previous 10 seconds every 10 seconds.

## Do I need to pay for Advanced Features to use the SDK event handlers?

**No**. The SDK-level events don't require Advanced Features. To view these events using the Console, turn on **Advanced Features**.

## How should I implement these events in my apps?

* To warn users that their local network conditions might impact call quality, implement handlers for *network-quality-warning-raised* group. To display warnings and prescriptive actions to users in the app, use the SDK. The warnings might include `check headset connection` or `move to an area with better WiFi`.
* To show visual indication to users that your app doesn't detect their audio, implement handlers for *audio-level-warning-raised* events.
* To identify commonalities in call behavior changes, create post-call surveys using feedback events. Ask your users to rate the subjective quality of experience and correlate responses with other metrics and properties.

## Why is the `To` property left blank for calls that the Voice SDK places?

A Voice SDK call uses the Twilio app SID for the `To` property value. The [TwiML][dial-app] returned from the webhook configured in the app SID creates a child call, and that child call contains the expected `To` property values.

## Why does Twilio see jitter only on the incoming stream of a call?

Twilio includes a small jitter buffer in its conference mixers. These can reduce or eliminate jitter on a received call before passing that call along to the other calls. This adds a proportional increase in latency.

## Can Twilio introduce jitter and packet loss?

**Yes**. The call on the incoming stream to Twilio might lack jitter or packet loss, but Twilio might see some jitter or packet loss on the outgoing stream of the child call. To send data, RTP media streams use the [*User Datagram Protocol* (UDP)][udp]. This protocol uses no error correction. UDP transport often results in jitter and packet loss. Calls that traverse large geographic distances might experience more jitter and packet loss.

## Why does this Voice SDK call have low bytes sent and received warning events, but no packet loss warning?

To indicate the number of packets sent from the gateway to the Voice SDK app, [*Web Real-Time Communication* (WebRTC)][webrtc] uses the [*Real-time Transport Control Protocol* (RTCP)][rtcp] ([RFC 3550][rfc3550]).

* If the RTCP sender reports that the sensors in the SDK expected, but didn't receive, packets, those expected-but-missing packets get calculated as packet loss.
* If the RTCP sender reports indicate that no packets were expected, the absence of packets get reported as low bytes sent or received.

## Why didn't users report issues when metrics infer poor call quality?

Transport-level metrics alone can't infer the subjective user experience. The understood experience of metrics exceeding certain threshholds include the following:

| Metric         | Exceeded value | User experience                                                                   |
| -------------- | -------------- | --------------------------------------------------------------------------------- |
| Packet loss    | 5%             | choppy audio                                                                      |
| Average jitter | 5              | robotic audio                                                                     |
| RTT            | 1000 ms        | people either talking over each other or long periods of silence between speakers |

Transport-level metrics provide approximate monitoring indicators of call quality. Some remediation exists.

* To mask jitter, some web browsers have adaptive jitter buffers. These introduce latency.
* To smooth out loss of packets, some codecs include packet loss concealment algorithms.
* SIP and PSTN carrier infrastructure might also implement jitter buffers or transcoding.

Twilio lacks data on jitter buffers or packet loss concealment activities at any given time. When lacking subjective feedback, Twilio reports on the underlying transport metrics.

## Can I be certain that a user experienced a detectable issue?

**No**. Twilio can't measure the performance of all network components. It can *infer* the subjective experience from objective metrics. Voice Insights tags calls using the ITU-T standards for VoIP quality.

To expose potential issues, Twilio tuned its performance based on years of customer feedback at the `detectable-but-tolerating` level. If Twilio waited to breach the `detectable-and-frustrated` or `frustrated-and-abandoning` thresholds, it couldn't remedy the issues.

Early alerting notifies developers of emerging issues before they become problems. These alerts guide users on what behaviors could influence the call in real time.

Each individual accepts different degrees of latency. Some users find high latency unacceptable. Other users might adjust their speech patterns for a transcontinental conference call. Some users balk at the first crackle of jitter while others can piece together choppy speech.

Your use case and your users' preferences dictate the severity of a problem. Don't rely on the metrics alone. Check with your users. Consider creating post-call surveys asking users to rate the subjective quality of experience and correlate responses with other metrics and properties to identify commonalities.

## Can Twilio detect if a Voice SDK user connects using VPN?

**No**. Insights receives the IP address of a VPN, not the local device location. You might infer VPN connectivity from conversations with users.

## Does Twilio know the mobile signal strength of the called party?

**No**. Twilio seeks to include signal strength and battery metrics for the mobile SDK. The [*Public Land Mobile Network* (PLMN)][plmn] conditions don't support them.

## Can Twilio check the external network status?

**No**. The metrics reported at the carrier gateway represent what Twilio receives from the [PSTN][]. Twilio's Super Network monitors these connections in real time and raises quality degradations to carriers and files incidents as appropriate. While you can check the status pages of destination carriers, these pages tend toward conservative reporting with slow updates.

Through proxy metrics like jitter, packet loss, and silence detection, Voice Insights can infer quality issues.

* Voice Insights can infer what Twilio sent to, and received from, its media edges.
* Voice Insights can't perceive degradation that poor signal strength or carrier issues might cause.

## Next steps

To build on what you've learned, explore the following guides:

* [Make outbound phone calls with Twilio Programmable Voice][]: Start placing calls programmatically using the REST API.
* [Record phone calls][]: Capture call audio for storage or transcription.
* [Respond to incoming phone calls][]: Learn how to handle inbound calls using TwiML.

## Related reference documentation

Find reference documentation for the topics on this page.

* [Account Report Resource][]
* [Call Annotation Resource][]
* [Call Insights API overview][]
* [Call Insights Event resource][]
* [Call Metric resource][]
* [Call Summaries resource][]
* [Call Summary resource][]
* [Conference Insights API overview][]
* [Conference Participant Summary resource][]
* [Conference Summary resource][]
* [Details: Call Summary][]
* [Details: Call tags][]
* [Details: Voice Insights SDK events][]
* [Inbound Phone Number Report resource][]
* [Outbound Phone Number Report resource][]
* [Voice Insights API overview][]
* [Voice Insights Reports API overview][]
* [Voice Insights Settings resource][]

[1c-voice-insights-calls]: https://1console.twilio.com/go?to=/account/__account__/us1/insights/voice/calls

[1c-voice-insights-settings]: https://1console.twilio.com/go?to=/account/__account__/us1/insights/voice/settings

[1c-voice-logs]: https://1console.twilio.com/go?to=/account/__account__/us1/logs/voice/calls

[Account Report Resource]: /docs/voice/voice-insights/api/reports-api/account-report-resource

[bye]: https://datatracker.ietf.org/doc/html/rfc3261#section-15.1

[Call Annotation Resource]: /docs/voice/voice-insights/api/call/call-annotation-resource

[Call Insights API overview]: /docs/voice/voice-insights/api/call

[Call Insights Event resource]: /docs/voice/voice-insights/api/call/call-events-resource

[Call Metric resource]: /docs/voice/voice-insights/api/call/call-metrics-resource

[Call Summaries resource]: /docs/voice/voice-insights/api/call/call-summaries-resource

[Call Summary resource]: /docs/voice/voice-insights/api/call/call-summary-resource

[Conference Insights API overview]: /docs/voice/voice-insights/api/conference

[Conference Participant Summary resource]: /docs/voice/voice-insights/api/conference/participant-summary-resource

[Conference Summary resource]: /docs/voice/voice-insights/api/conference/conference-summary-resource

[Details: Call Summary]: /docs/voice/voice-insights/api/call/details-call-summary

[Details: Call tags]: /docs/voice/voice-insights/api/call/details-call-tags

[Details: Voice Insights SDK events]: /docs/voice/voice-insights/api/call/details-sdk-call-quality-events

[dial-app]: /docs/voice/twiml/dial/application/usage

[Elastic SIP Trunking]: /docs/sip-trunking

[Inbound Phone Number Report resource]: /docs/voice/voice-insights/api/reports-api/inbound-phone-number-report-resource

[itu-t]: https://www.itu.int/en/ITU-T/Pages/default.aspx

[jitter buffer]: https://www.twilio.com/blog/improve-call-experience-new-twilio-conference-jitter-buffer-controls

[jitter]: /docs/glossary/what-is-jitter

[lc-voice-insights-calls]: https://console.twilio.com/us1/monitor/insights/voice/calls

[lc-voice-insights-settings]: https://www.twilio.com/console/voice/insights/settings

[lc-voice-logs]: https://console.twilio.com/us1/monitor/logs/calls

[Make outbound phone calls with Twilio Programmable Voice]: /docs/voice/tutorials/how-to-make-outbound-phone-calls

[mobile SDKs for Android and iOS]: /docs/voice/sdks/android/get-started

[Outbound Phone Number Report resource]: /docs/voice/voice-insights/api/reports-api/outbound-phone-number-report-resource

[packet loss]: /docs/glossary/what-is-packet-loss

[pcap]: https://en.wikipedia.org/wiki/Pcap

[plmn]: https://en.wikipedia.org/wiki/Public_land_mobile_network

[post-dial delay]: /docs/glossary/what-is-post-dial-delay

[pstn]: /docs/glossary/what-is-pstn

[Record phone calls]: /docs/voice/tutorials/how-to-record-phone-calls

[Related reference documentation]: #related-reference-documentation

[Respond to incoming phone calls]: /docs/voice/tutorials/how-to-respond-to-incoming-phone-calls

[rfc3550]: https://datatracker.ietf.org/doc/html/rfc3550

[rtcp]: https://en.wikipedia.org/wiki/RTP_Control_Protocol

[rtp]: https://en.wikipedia.org/wiki/Real-time_Transport_Protocol

[Twilio Support]: https://help.twilio.com

[udp]: https://en.wikipedia.org/wiki/User_Datagram_Protocol

[Voice APIs]: https://www.twilio.com/en-us/voice

[Voice Insights API overview]: /docs/voice/voice-insights/api

[Voice Insights Reports API overview]: /docs/voice/voice-insights/api/reports-api

[Voice Insights Settings resource]: /docs/voice/voice-insights/api/call/voice-insights-settings-resource

[Voice SDKs for JavaScript]: /docs/voice/sdks/javascript

[voip]: /docs/glossary/what-is-voip

[webrtc]: /docs/glossary/what-is-webrtc