Voice Insights Frequently Asked Questions

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

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.

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.

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.

Communications use network, not voice, infrastructure. Public Switched Telephone Network (PSTN) only concerns itself with the physical continuity of copper wires between locations. Voice over IP (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:

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.

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.

Twilio's media gateways can detect missing Real-Time Transport Protocol (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.

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

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.

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 or Legacy Console.

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.

Twilio bases its quality thresholds on International Telecommunication Union Telecommunication Standardization Sector (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.

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.

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.

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.

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

To comply with 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.

This depends on the source of the errors.

Compare your local SIP infrastructure logs and Packet Captures (PCAP) with the Twilio public PCAPs in the Calls page of the Twilio Console (legacy Console).

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.

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.

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

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

• The Voice Insight Dashboard (legacy Console) 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 (legacy Console) 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.

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.
   • In the legacy Console, go to Monitor > Insights > Voice > Settings.
2. Click Select. The Change to Voice Insights Advanced Features modal appears.
3. Click Confirm Change.

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

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.

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.

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.
• In the legacy Console, go to Monitor > Insights > Voice > 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.

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.

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.

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

• 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.

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

• 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.

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

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.

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). 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.

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

• 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.

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

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.

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.

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

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

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.

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.

Find reference documentation for the topics on this page.