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?

Client Insights Preview API Migration Guide

About

The beta for Client Insights ended on August 5, 2019 and was superseded by the general availability of Voice Insights. The Client Insights Dashboard was removed from Console at that time, though we have continued to respond to requests made to the preview API. Twilio will cease responding to API requests to preview resources on May 1, 2020. Any HTTP requests to preview resources after this date will result in a 404 response from the API.

If your application is currently making requests to any of the preview API endpoints described below, you will need to migrate to the new Voice Insights API endpoints. For more information see here.

Note that the preview API responses were limited to calls placed using Twilio Client SDKs. SIP Trunking, SIP Interface, and PSTN calls would not return results when queried via the preview API. The new Insights API provides events, metrics, and summaries for all call types, and as such the Client call details that were the primary focus of the preview API represent a fraction of the detail available via the new endpoint.

This increased scope has resulted in some additional granularity in the responses, and some attendant additional complexity when consuming resources from the new endpoints.

/Events

The Events endpoint provides details on state transitions that occur during call, warnings related to deteriorating network quality, audio equipment malfunction, and other SDK-specific events.

/Events Query Parameters

Parameter

Preview API

Insights API

Level

INFO, DEBUG, WARNING, ERROR

-

Group

SDK Event Groups

-

Name

SDK Event Names

-

Edge

-

carrier_edge | sip_edge | sdk_edge | client_edge

Note: all of the events previously available via the preview API are associated with the sdk_edge. See Understanding Twilio Media Edges for more information.

/Events Event Properties

Preview API

Insights API

group

group

name

name

level

level

timestamp

timestamp (according RFC 3339, with 3 fractional digits)

account_sid

account_sid

payload_type

-

payload

sdk_edge | client_edge

sid

-

account_friendly_name

-

parent_account_friendly_name

-

parent_account_sid

-

publisher

sdk_edge.metadata.sdk.type

publisher_metadata

See below

-

call_sid

-

edge

Note: all of the events previously available via the preview API are associated with the sdk_edge. See Understanding Twilio Media Edges for more information.

/Events Publisher Metadata

Preview API

Insights API

publisher_metadata.city

sdk_edge.metadata.city

publisher_metadata.cpu_architecture

sdk_edge.metadata.sdk.device.arch

publisher_metadata.engine_name

sdk_edge.metadata.sdk.engine.name

publisher_metadata.location.lat

sdk_edge.metadata.location.lat

publisher_metadata.location.lon

sdk_edge.metadata.location.lon

publisher_metadata.os_version

sdk_edge.metadata.sdk.os.version

publisher_metadata.os_name

sdk_edge.metadata.sdk.os.name

publisher_metadata.country_iso_code

sdk_edge.metadata.country_code

publisher_metadata.country

-

publisher_metadata.user_agent

-

publisher_metadata.device_model

sdk_edge.metadata.sdk.device.model

publisher_metadata.device_type

sdk_edge.metadata.sdk.device.type

publisher_metadata.device_vendor

sdk_edge.metadata.sdk.device.vendor

publisher_metadata.browser_major

sdk_edge.metadata.sdk.browser.major

publisher_metadata.engine_version

sdk_edge.metadata.sdk.engine.version

publisher_metadata.browser_version

sdk_edge.metadata.sdk.browser.version

publisher_metadata.client_address

sdk_edge.metadata.ip_address

publisher_metadata.browser_name

sdk_edge.metadata.sdk.browser.name

publisher_metadata.specific_subdivision

sdk_edge.metadata.country_subdivision

/Events Payload

Preview API

Insights API

payload.client_name

sdk_edge.metadata.client_name

payload.direction

Summary -> client_edge.properties.direction (reverse)*

payload.gateway

Summary -> client_edge.properties.twilio_media_ip

payload.temp_call_sid

-

payload.selected_region

sdk_edge.metadata.sdk.selected_region

payload.region

sdk_edge.metadata.sdk.region

payload.sdk_version

sdk_edge.metadata.sdk.version

payload.platform

sdk_edge.metadata.sdk.platform

payload.audioConstraints

-

payload.timestamp_ms

timestamp

payload.data

-

-

sdk_edge.error.code

-

sdk_edge.feedback.score

-

sdk_edge.feedback.reason

*By reverse we mean the direction is the opposite in the new API compared to the preview API. From the perspective the preview API a call to to Twilio was an outbound call, but from the perspective of Twilio's signaling edge the call is an inbound call. Since these details have been moved from the SDK to the Client edge, the direction is reversed. See Understanding Twilio Media Edges for more information.


/Metrics

/Metrics Query Parameters

Parameter

Preview API

Insights API

Edge

-

sdk_edge | client_edge

Direction

-

inbound | outbound | both

Note: all of the metrics previously available via the preview API are associated with the sdk_edge.

/Metrics Properties

Preview API

Insights API

call_sid

call_sid

timestamp

timestamp

(according RFC 3339, with 3 fractional digits)

timestamp_ms

-

jitter

sdk_edge.interval.jitter.value

mos

sdk_edge.interval.mos.value

rtt

sdk_edge.interval.rtt.value

audio_level_out

sdk_edge.interval.audio_out.value

audio_level_in

sdk_edge.interval.audio_in.value

packets_received

sdk_edge.interval.packets_received

packets_lost

sdk_edge.interval.packets_lost

packets_lost_fraction

sdk_edge.interval.packets_loss_percentage

total_packets_received

sdk_edge.cumulative.packets_received

total_packets_lost

sdk_edge.cumulative.packets_lost

total_bytes_sent

sdk_edge.cumulative.bytes_sent

total_bytes_received

sdk_edge.cumulative.bytes_received

total_packets_sent

sdk_edge.cumulative.packets_sent

/Summary

The call summary resource provides an overview of metadata and quality metrics for a single call.


/Summary Resource

Preview API

Insights API

account_sid

account_sid

account_friendly_name

-

parent_account_friendly_name

-

parent_account_sid

-

call_sid

call_sid

summary

carrier_edge | sip_edge | sdk_edge | client_edge

url

url

Note: all of the events and metrics previously available via the preview API are associated with the sdk_edge.


/Summary Summary Object

Preview API

Insights API

summary.publisher_metadata

See below

summary.events

See below

summary.metrics

See below

summary.client_metadata

See below

summary.error_counts_unique

See below

summary.feedback

See below


/Summary Publisher Metadata

Based on properties.direction the publisher metadata will either be in to.whatever or from.whatever. For an inbound call to Twilio from a Client SDK application the publisher metadata will be contained in the from; outbound calls to Client SDK application destinations will be available in the to.

Preview API

Insights API

summary.publisher_metadata.city

{to|from}.city

summary.publisher_metadata.os_name

{to|from}.sdk.os.name

summary.publisher_metadata.specific_subdivision

{to|from}.country_subdivision

summary.publisher_metadata.engine_name

{to|from}.sdk.engine.name

summary.publisher_metadata.country_iso_code

{to|from}.country_code

summary.publisher_metadata.country

-

summary.publisher_metadata.cpu_architecture

{to|from}.sdk.device.arch

summary.publisher_metadata.engine_version

{to|from}.sdk.engine.version

summary.publisher_metadata.browser_name

{to|from}.sdk.browser.name

summary.publisher_metadata.device_model

{to|from}.sdk.device.model

summary.publisher_metadata.browser_version

{to|from}.sdk.browser.major

summary.publisher_metadata.os_version

{to|from}.sdk.os.version

summary.publisher_metadata.location.lat

{to|from}.location.lat

summary.publisher_metadata.location.lon

{to|from}.location.lon

summary.publisher_metadata.device_type

{to|from}.sdk.type

summary.publisher_metadata.device_vendor

{to|from}.sdk.device.vendor

summary.publisher_metadata.browser_major

{to|from}.sdk.browser.major

summary.publisher_metadata.client_address

{to|from}.ip_address

summary.publisher_metadata.user_agent

-

/Summary Events

Preview API

Insights API

summary.events.levels.{}

Will be added in an upcoming release

summary.events.groups.{}

Will be added in an upcoming release

/Summary Metrics

Preview API

Insights API

summary.metrics.packets_lost

sdk_edge.metrics.inbound.packets_lost

summary.metrics.mos

sdk_edge.metrics.inbound.mos

(min|max|avg)

summary.metrics.packets_received

sdk_edge.metrics.inbound.packets_received

summary.metrics.rtt

sdk_edge.metrics.inbound.rtt

(min|max|avg)

summary.metrics.audio_level_out

-

summary.metrics.jitter

sdk_edge.metrics.inbound.jitter

(max|avg)

summary.metrics.packets_sent

sdk_edge.metrics.outbound.packets_sent

summary.metrics.audio_level_in

-

/Summary Client Metadata

Preview API

Insights API

summary.client_metadata.direction

client_edge.properties.direction*

(reverse)

summary.client_metadata.selected_region

{to|from}.sdk.selected_region

summary.client_metadata.region

{to|from}.sdk.region

summary.client_metadata.platform

{to|from}.sdk.platform

summary.client_metadata.sdk_version

{to|from}.sdk.version

summary.client_metadata.disconnected_by

sdk_edge.properties.disconnected_by

summary.client_metadata.client_name

{to.callee|from.caller}

(strip client: prefix)

*By reverse we mean the direction is the opposite in the new API compared to the preview API. From the perspective the preview API a call to to Twilio was an outbound call, but from the perspective of Twilio's signaling edge the call is an inbound call. Since these details have been moved from the SDK to the Client edge, the direction is reversed. See Understanding Twilio Media Edges for more information.

/Summary Error Counts Unique

Preview API

Insights API

summary.error_counts_unique.{}

Will be added in an upcoming release


/Summary Feedback

Preview API

Insights API

summary.feedback.[]

Will be added in an upcoming release


/Reports

The Reports API endpoint provided during the beta will not be directly replaced in the new Insights API. We are working on a reporting solution to provide similar functionality to the preview Reports API, but there is no timeline we can offer at this time regarding its availability.

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.