Call Summary Resource
Fetch a Call Summary
The call summary resource provides an overview of metadata and quality metrics for a single call. A completed call summary may take up to a half hour to generate, but a partial summary record will be available within ten minutes of a call ending.
GET https://insights.twilio.com/v1/Voice/{CALL_SID}/Summary
Resource Properties
A call summary is represented by the following properties:
| Property | Description |
|---|---|
| account_sid | The account SID this call belongs to |
| attributes | Contains call-flow specific details |
| call_sid | SID for the call |
| call_state | Status of the call; completed, failed, etc. |
| call_type | Describes the call type; client, carrier, sip, trunking |
| carrier_edge | Contains metrics and properties for the Twilio media gateway of a PSTN call |
| client_edge | Contains metrics and properties for the Twilio media gateway of a Client call |
| connect_duration | Duration between when the call was answered and when it ended |
| created_time | Time the call resource was created. Can be different from start_time in the event of queueing due to CPS. |
| duration | Duration between when the call was initiated and the call was ended |
| end_time | Call end time |
| from | The calling party |
| parent_account_sid | Parent account SID for calls placed using subaccounts. |
| parent_call_sid | Parent call SID for |
| processing_state | Represents the summarization state of the resource. While the call is in-progress and as we begin assembling the final summary when the call is completed the processing_state will be partial. We will continue to assemble the summary for approximately 30 minutes, after which the processing_state will be changed to complete. The Summary endpoint can be queried for partial summaries by appending ?ProcessingState=partial to the URI. |
| processing_version | Increments as updates to the summary are made while processing_state is partial. Allows developers to look at processing version instead of state to potentially close books on a call summary sooner than the 30 minute timeout for processing state; e.g. if your calls always contain 6 processing versions that are completed within 5 minutes, you could conceivably get 25 minutes head start using the data with high confidence. |
| answered_by | If Answering Machine Detection (AMD) is enabled for a call, the answered_by field would contain the results of AMD for that call. AMD enables you to determine the receiving side of an outgoing call and tailor your call flow accordingly. With AMD, you can determine if a human, answering machine or fax machine has picked up an outbound voice API call. |
| properties | Contains edge-agnostic call-level details. |
| sdk_edge | Contains metrics and properties for the SDK sensor library for Client calls. |
| sip_edge | Contains metrics and properties for the Twilio media gateway of a SIP Interface or Trunking call |
| start_time | Call start time |
| tags | Tags applied to calls by Voice Insights analysis indicating a condition that could result in subjective degradation of the call quality. |
| to | The called party |
| trust | Contains trusted communications details including Branded Call and verified caller ID |
| annotation | Programmatically labeled annotations for the call. Developers can update the call summary records with annotation during or after a call. Annotations can be updated as long as the Call Summary record is addressable via the API. |
| url | The URL of the Voice Insights Summary for this call |
Properties object properties
Edge-agnostic call-level details.
| Property | Description |
|---|---|
| pdd_ms | Post-dial delay in milliseconds |
| last_sip_response_num | The numeric value of the last SIP response received for the call |
| direction | The direction of the call; inbound, outbound-api, outbound-dial, trunking-originating, trunking-terminating |
| disconnected_by | Direction of the SIP BYE received at Twilio signaling gateway. |
| queue_time | Estimated time in milliseconds between when a Programmable Voice call is created and when the call actually begins. |
Attributes object properties
Call-flow specific details.
| Property | Description |
|---|---|
| conference_participant | True/false. Indicates if primary media source was a Twilio conference mixer. |
To/From object properties
Additional metadata for Voice SDK calls.
| Property | Description |
|---|---|
| callee | Dialed destination |
| caller | Caller ID of calling party |
| carrier | Serving carrier of destination |
| connection | landline, mobile, voip |
| country_code | Two-letter ISO country code |
| country_subdivision | Additional location details; e.g. California |
| city | City name based on lat/long or IP address |
| location | Lat/long for number prefix |
| ip_address | Public IP of Client user |
| number_prefix | E.164 country code + three digits |
SDK object properties
Additional metadata for Voice SDK calls.
| Property | Description |
|---|---|
| type | Version of Twilio SDK; e.g. twilio-js-sdk. twilio-voice-android |
| version | Twilio SDK version |
| platform | WebRTC, android, iOS |
| region | The Twilio region the device registered to |
| selected_region | The region specified in the device setup |
| edge_location | The edge location specified |
| browser.name | Name of browser for calls placed using JavaScript SDK |
| browser.major | Major version of browser |
| browser.version | Full version of browser |
| os.name | Operating system name as reported to the SDK |
| os.version | Operating system version as reported to the SDK |
| device.arch | Processor architecture of machine running the Client app; e.g. amd64 |
| device.model | Mobile SDKs only: model name/number reported to the SDK |
| device.type | Mobile SDKs only: device type reported to the SDK |
| device.vendor | Mobile SDKs only: hardware manufacturer reported to the SDK |
| engine.name | JavaScript SDK only: browser engine as detected by the SDK |
| engine.version | JavaScript SDK only: browser engine version detected by the SDK |
Edges
There are four possible edges: carrier_edge, client_edge, sdk_edge, and sip_edge. SIP trunking calls will have both a carrier_edge and a sip_edge. Client calls will have both an sdk_edge and a client_edge.
carrier_edge represents the connection between Twilio and our immediate carrier partners. The metrics here describe the media stream metadata as it was received from the carrier on the inbound, and as it was delivered to the carrier on the outbound.
client_edge represents the Twilio media gateway for Client calls. The metrics here describe the media stream metadata as it was received from the Client SDK application on the inbound, and as it was sent to the Client SDK application on the outbound.
NOTE: Voice Insights for mobile SDKs is supported for versions 3.x and later. Calls placed using 2.x mobile SDKs are not supported and details are provided as-is and may not be reliable indicators of actual performance on the handset or subjective experience on the call.
sip_edge represents the Twilio media gateway for SIP interface and SIP trunking calls. The metrics here describe what was received from your SIP infrastructure on the inbound, and what was delivered to your SIP infrastructure on the outbound.
Each edge has two child objects: metrics and properties. metrics will have a container for inbound and outbound media streams.
Edge Metrics object properties
| Property | Description |
|---|---|
| codec | RTP profile number for the media codec |
| codec_name | Name of the media codec |
| packets_received | Count of packets received; inbound container only |
| packets_sent | Count of packets sent; outbound container only |
| packets_lost | Count of packets lost |
| packets_loss_percentage | Percentage of packets lost |
| jitter | Average and max jitter detected |
| latency | Twilio internal RTP traversal time from ingress to egress. Average and max latency detected. |
| packet_delay_variation | Distribution of packets delayed by a certain value; e.g. "d50": 24 indicates that 24 packets were delayed by more than 50 ms. |
Edge Properties object properties
| Property | Description |
|---|---|
| q850_cause | ITU-T Q.850 standard definition of telephony disconnect cause. Not available for all edge types or all calls. |
| direction | Direction of media flow from the perspective of the edge. Inbound or outbound. |
| media_region | The Twilio region where media was handled. |
| signaling_region | The Twilio region where signaling was handled. |
| edge_location | The Twilio edge location where media was handled. |
| twilio_media_ip | The IP address for Twilio's media gateway. Not available for carrier_edge. |
| twilio_signaling_ip | The IP address for Twilio's signaling gateway. Not available for carrier_edge. |
| external_media_ip | The IP address Twilio received media from. Not available for carrier_edge. |
| external_signaling_ip | The IP address Twilio received signaling from. Not available for carrier_edge. |
| sip_call_id | SIP call ID for the call between Twilio & your SIP infrastructure. Present on SIP Interface and trunking calls only. |
| user_agent | Available for trunking calls only |
| selected_region | Available for Client calls only. |
| region | Available for Client calls only. |
| disconnected_by | Available for Client calls only. Identifies if Twilio.Device.disconnect() was called in the local application or if the call was ended by remote party |
| trunk_sid | The trunk SID for this call. Present on trunking calls only. |
sdk_edge Metrics object properties
sdk_edge represents the sensor library in the SDK application itself. The metrics here describe the media stream that was received at the SDK from the Twilio media gateway. Packet loss, jitter, MOS, and RTT are reporting on the inbound stream to the SDK. Audio in/audio out levels can be used to detect one-way audio; no audio in indicates an issue with microphone, potentially muting, hardware issue, or browser loss of context for OS audio APIs.
| Property | Description |
|---|---|
| mos | Mean opinion score; a function of jitter, packet loss, and round-trip time. Scale of 0-5 where anything above 4 is considered acceptable. Average, maximum, and minimum values returned. |
| rtt | Round-trip time; time in milliseconds for packets sent from Twilio's gateway to arrive at the SDK. NOTE: adaptive jitter buffers and dynamic packet loss concealment algorithms may delay actual play out of RTP beyond the RTT value. Average, maximum, and minimum values returned. |
| packets_received | Count of packets received; inbound container only |
| packets_sent | Count of packets sent; outbound container only |
| packets_lost | Count of packets lost |
| packets_loss_percentage | Percentage of packets lost |
| jitter | Average and max jitter detected |
| tags | Tags applied to calls by Voice Insights analysis indicating a condition that could result in subjective degradation of the call quality |
| bytes_received | Bytes received at the SDK sensors |
| bytes_sent | Bytes sent from the SDK |
| inbound.audio_out | Avg/max level for speaker audio |
| inbound.audio_in | Avg/max level for microphone audio |
| outbound.codec_name | Friendly name of the RTP codec for the call set in Twilio.Device(); |
| outbound.codec | RTP profile number of the codec for the call set in Twilio.Device(); |
sdk_edge Properties object properties
| Property | Description |
|---|---|
| direction | Direction of the call from the perspective of the SDK. |
| settings.dscp | Indicates whether DSCP was enabled. |
| settings.ice_restart_enabled | Indicates if ICE restart was enabled. |
| settings.edge | Twilio Edge Location that was used for this call |
| settings.selected_edges | Prioritized list of Edge Locations provided during Twilio.Device.setup(); |
sdk_edge Events object properties
| Property | Description |
|---|---|
| levels | Count of events by severity for the call. |
| groups | Count of events by the event group. |
| errors | Error code and number of occurrences. |
| feedback | User feedback gathered from the SDK. |
Trust Properties
| Property | Description |
|---|---|
| branded_call.branded | Boolean. Indicates if branding details were successfully displayed on the destination device. |
| branded_call.caller | Caller ID provided. |
| branded_call.use_case | Use case for the call. |
| branded_call.branded_channel_sid | Branded channel SID. |
| branded_call.business_sid | Business SID. |
| branded_call.brand_sid | Brand SID. |
| verified_caller.verified | Boolean. Indicates if the caller ID provided has been verified; e.g. SHAKEN/STIR A attestation. |
Annotation Properties
Each call summary can be programatically labeled by the developers to add subjective information pertaining to that call. More details on Call Annotation resource can be found here.
| Property | Description |
|---|---|
| answered_by | Enumerated. Which entity answered the call as determined by Answering Machine Detection (AMD). Use this to provide feedback on AMD accuracy. |
| connectivity_issue | Enumerated. Indicates if the call was labeled for any connectivity issues. |
| quality_issues | String[]. Indicates if the call was labeled for user perceived quality issues. |
| spam | Boolean. Indicates if the call was labeled as a spam call. |
| call_score | Integer. Indicates the labeled call score for that call. |
| comment | String. Indicates if any comments were added for the call. |
| incident | String. Indicates if any associated incident or support tickets were added for the call. |
Consuming the Summary API
The call summary API is fairly deep. There is a top level object with attributes and properties, and each edge has metrics for both directions of the media stream as well as properties and summarized metrics, so an application trying to access the max jitter value on the outbound stream of a Client call would need to retrieve client_edge.metrics.outbound.jitter.max.
Not all applications will require that level of detail; simply knowing whether or not jitter was detected on the call will suffice, so just checking the top-level tags will answer that question.
The edge(s) present will depend on the call type. A Voice SDK call will have an sdk_edge and a client_edge. A SIP trunking call will have a sip_edge and a carrier_edge. A SIP domain or <Dial><Sip> call will have only a sip_edge. A PSTN call will have only a carrier_edge.
See Understanding Twilio Media Edges for more details.
Read multiple Call Summary resources
The Call Summary list API allows results to be filtered by date, to/from information, call state, and other dimensions.
GET https://insights.twilio.com/v1/Voice/Summaries
The following query string parameters allow you to filter and limit the list returned to you by the REST API. These parameters are case-sensitive.
Parameters in REST API format
| Parameter | Type | PII | Description |
|---|---|---|---|
| Subaccount | String | Not PII | The SID of the subaccount that created the call resource(s) to read. Allows parent accounts to make requests of subaccount resources without needing subaccount authentication key and token. |
| To | String | PII MTL:120 Days | The called party. Could be an E.164 number, a SIP URI, or a Twilio Client registered name. |
| From | String | PII MTL:120 Days | The calling party. Could be an E.164 number, a SIP URI, or a Twilio Client registered name. |
| ToCarrier | String | Not PII | The destination carrier. |
| FromCarrier | String | Not PII | The origination carrier. |
| ToCountryCode | String | Not PII | The destination country code. Based on phone number in To. |
| FromCountryCode | String | Not PII | The source country code. Based on phone number in From. |
| Branded | Boolean | Not PII | Indicates whether or not a call was branded using Twilio Branded Calls. |
| VerifiedCaller | Boolean | Not PII | Indicates whether or not the caller was verified using SHAKEN/STIR. |
| HasTag | Boolean | Not PII | Indicates the presence of one or more Voice Insights Call Tags. |
| AbnormalSession | Boolean | Not PII | Indicates the last SIP response was not 200 OK. |
| StartTime | String | Not PII | Start time of the calls. xm (x minutes), xh (x hours), xd (x days), 1w, 30m, 3d, 4w or datetime-ISO. Defaults to 4h. |
| EndTime | String | Not PII | End time of the calls. xm (x minutes), xh (x hours), xd (x days), 1w, 30m, 3d, 4w or datetime-ISO. Defaults to 0m. |
| CallType | String | Not PII | carrier, sip, client, trunking |
| CallState | String | Not PII | Final call status |
| Direction | String | Not PII | outbound_api, outbound_dial, inbound, trunking_originating, trunking_terminating |
| SortBy | String | Not PII | start_time, end_time. Defaults to end_time. |
| ProcessingState | String | Not PII | partial, completed, all. Defaults to completed. |
| AnsweredBy | String | Not PII | The result of Answering Machine Detection (AMD). Results can be: machine_start, machine_end_beep, machine_end_silence, machine_end_other, human, fax, unknown. Refer to AMD for more details. |
| PageSize | String | Not PII | defaults to 25 |
| PageToken | String | Not PII |
Paging
If you are using the Twilio REST API, the list returned to you includes paging information.
If you plan to request more records than will fit on a single page, you can use the provided nextpageuri rather than incrementing through pages by page number.
Using nextpageuri for paging ensures that your next request will pick up where you left off. This can help keep you from retrieving duplicate data if you are actively making or receiving calls.
All of the Twilio Helper Libraries handle paging automatically. You do not need to explicitly request individual pages when using a Helper Library to fetch lists of resources.
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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
