Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Voice Insights Advanced Features

Call metrics, event streams, and API access

Voice Insights data is gathered for every call placed on Twilio. Aggregate dashboards and call summaries are included with every voice minute placed on Twilio, but high-precision metrics, call progress events, and programmatic availability are must-haves for certain applications. For customers who require greater specificity about call behavior or have advanced analytics applications we are offering a set of features tuned to operating highly sensitive and complex call quality monitoring.

Metrics

Time-series view of jitter, packet loss, and packet rate for inbound and outbound streams for carrier and trunking calls; jitter, received packet loss, mean opinion score, round trip time, and audio input/output levels for voice SDK calls.

In some cases just knowing that call metric variance may have degraded the experience on a call is not enough. If you need to know precisely when during the call the variance occurred, and for how long, you need a time series view of that data.

Events

The Events stream will show Twilio call progress events for Programmable Voice calls, SIP signaling responses for trunking calls, and Twilio Device and ICE connection events for Voice SDK calls.

Twilio's SDKs provide a rich source of call data in the form of debug, error, info, and warning events. These events are available to your application via the SDK, but enriching the Twilio call record with the event stream provides additional context for understanding call behavior. Call progress events like the transition from ringing to answered are also provided.

API

If your use case requires programmatic access to Voice Insights data we have a converged API endpoint available to retrieve post-call summaries for your calls. Pull the data about your calls into your own applications and decorate your call records with the details provided by Insights.

Learn more about the Summary API here.

Pricing

Advanced features are available at $0.0025 per minute. Delve deeper into your call behavior by ednabling Voice Insights advanced features here.

Enabling Voice Insights advanced features

To enable Voice Insights, login to console with your Twilio account, switch to the Programmable Voice section using the phone icon in the left nav. Under the Insights tab, visit the settings section in the left nav. Choose the checkbox to enable Voice Insights advanced features. Click Save. Insights is now enabled. To enable Insights for your subaccounts, switch to the subaccount and enable Insights from the settings.

Voice Insights Settings

Events

The event stream 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 Twilio Voice SDKs fail to connect with Twilio servers. These failures can occur because of severe network degradation or due to a firewall. There are two views: Event Stream and Event List.

The Event Stream view displays the progress of the events horizontally. In some cases where, for example, a Voice SDK call has a large number of ICE connection changes the number of Events can exceed what will fit on the horizontal view, so while all of the Events are visible and selectable on the timeline, only a portion of the Events will have titles and timestamps shown.

Event Stream

The Event list view shows all the events ordered by timestamp regardless of how many there are; as mentioned above longer calls placed with Voice SDKs or calls in troublesome network conditions can result in there being hundreds of events.

Event List

Metrics

Metrics are gathered at Twilio's media gateways and by sensors in the Voice SDKs. We gather metrics every second for Voice SDK calls, and every 10 seconds for SIP/Carrier calls (cumulative statistics for the previous 10 seconds). The dotted orange threshold lines on the graphs indicate the values beyond which there is perceivable drop in call quality. The threshold line is based on the ITU-T standards for VoIP quality.

Twilio Gateway Metrics

Twilio Gateway Metrics

Voice SDK Metrics

Voice SDK calls have additional Metrics which represent what the SDK sensors received from the Twilio Gateway.

SDK Metrics

For Elastic SIP Trunking and Voice SDK calls you can choose between multiple views on a single page. For SDK calls there will be an SDK view which represents what was sent to and reported by the sensors at the Voice SDK, and a Twilio Gateway view that shows what was received at Twilio's media edge from the SDK and what was sent to the SDK from the parent/child. Similarly Elastic SIP Trunking calls will have two views, SIP/PBX view which shows what was sent to and received from your SIP infrastructure, and a Twilio Gateway view which will show what was sent to/received from the Carrier gateway.

Metrics View Selector

The Metrics graphs can be zoomed in by selecting the region of the graph you are interested in viewing in greater detail. Once zoomed in click on Zoom Out to restore the view.

Zoom Out

Interpreting Metrics Graphs

Here is an example of Voice SDK call with some transport issues. First, let's look at the Twilio Gateway view.

Voice Insights Metrics Gateway View

There are a couple things worth taking a closer look at here.

1. Jitter on the stream received at the Twilio Gateway from the Voice SDK. Though the max jitter never breaches the ITU-T threshold of 30ms the average jitter exceeds our threshold, so the line is red in the the graph.

2. Jitter on the stream sent to the Voice SDK from the Twilio Gateway. Almost the inverse of the other graph, the average jitter stays low, but the max jitter exceeds the 30ms threshold significantly. Note that the max jitter will remain the max jitter until it is surpassed; for example in the screenshot above it looks like a handful of packets arrived out of order, so the max is set a 101ms and stays there for the rest of the call because the max stays the max unless it is surpassed.

3. Packet loss on the stream received at the Twilio Gateway from the Voice SDK. We can see multiple brief spikes of packet loss, but the percentage of packet loss never exceeds our threshold, so the graphical representation stays under the yellow line.

4. Inconsistent packet rate on the stream sent to the Voice SDK from the Twilio Gateway.

Here's the SDK view for this same call.

image2019-7-26_12-56-30.png

The SDK view reports what was received at the SDK sensors from the Twilio Gateway. Here we can see a jump in jitter received at the SDK (see #1) at the same time max outbound jitter spikes on the graph above (#2).

Rate this page:

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.