Call Summary Resource
通話サマリーを取得する
The call summary resource provides an overview of metadata and quality metrics for a single call. A completed call summary may take up to one 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/{SID}/Summary
リソースのプロパティ
A call summary is represented by the following properties:
| プロパティ | 概要 |
|---|---|
| account_sid | The account SID this call belongs to |
| 属性 | 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 |
| Duration | Duration between when the call was initiated and the call was ended |
| end_time | Call end time |
| from | The calling party |
| 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 one hour, 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. |
| プロパティ | 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 |
| url | The URL of the Voice Insights Summary for this call |
Properties object properties
Edge-agnostic call-level details.
| プロパティ | 概要 |
|---|---|
| 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. |
Attributes object properties
Call-flow specific details.
| プロパティ | 概要 |
|---|---|
| conference_participant | True/false. Indicates if primary media source was a Twilio conference mixer. |
To/From object properties
Additional metadata for Voice SDK calls.
| プロパティ | 概要 |
|---|---|
| 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 |
| 住所3(市区町村) | 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.
| プロパティ | 概要 |
|---|---|
| タイプ | Version of Twilio SDK; e.g. twilio-js-sdk. twilio-voice-android |
| version | Twilio SDK version |
| プラットフォーム | WebRTC, android, iOS |
| region | The Twilio region the device registered to |
| selected_region | The region specified in the device setup |
| 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.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
| プロパティ | 概要 |
|---|---|
| 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
| プロパティ | 概要 |
|---|---|
| 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. |
| 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.
| プロパティ | 概要 |
|---|---|
| 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. |
Tags
Calls can be tagged for one or more conditions that may impact the subjective experience of quality on the call. Tags are based on analysis of the call at the Twilio Gateway. The tags at initial release are:
- silence: silence detected on the line; either due to a missing audio stream or a completely silent stream received
- high_jitter: two conditions can result in calls being tagged with high jitter, average jitter of 5ms and max jitter of 30ms, or more than 1% of packets delayed by 200ms or more
- high_packet_loss: >5% packet loss
- high_pdd: post-dial delay (time between SIP INVITE and 18x response) > p95 for this country
- high_latency: the Twilio-internal RTP traversal time exceeded 150ms
SDK Edge Tags
SDK Tags are based on analysis of the call at the SDK sensors on the local device. They report on the condition of the media streams sent to the SDK from the Twilio Gateway.
- high_latency: Round Trip Time (RTT) > 400 ms for 3 out of last 5 samples
- low_mos: Mean Opinion Score (MOS) < 3.5 for 3 out of last 5 samples
- high_jitter: Jitter > 30 ms for 3 out of last 5 samples
- high_packet_loss: Packet loss > 1% in 3 out of last 5 samples
- ice_failure: The ICE candidate has checked all candidates pairs against one another and has failed to find compatible matches for all components of the connection.
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.
Understanding Edges
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.
Each edge will have an inbound and outbound stream representing what was received at and sent from the edge in question. For SIP trunking calls the two edges represent the entire media session due to SIP trunking calls bypassing the Programmable Voice infrastructure; however, for other call types one of the media streams will be from the "other side" of the call–i.e. the parent/child call or conference mixer.
With this in mind it's important to understand when you are looking at, for example, the outbound stream being passed to your SIP infrastructure on a SIP domain call the source of that stream is the inbound stream received on the carrier edge on the parent or child call.
ヘルプが必要ですか？
誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。