Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Rate this page:
On this page

Call Summary Resource

A Call Summary provides an overview of

  • metadata, and
  • quality metrics

for a single call.

Using the Call Summary Resource, you can get a single summary for a specific Call.

To get a list of Call Summaries for multiple calls use the Call Summaries Resource.

(warning)

Warning

Voice Insights Advanced Features must be active to use this API Resource.

(information)

Info

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.

Call Summary properties

call-summary-properties page anchor

The following table contains the top-level properties of a single Call Summary instance.

A Call Summary is a complex data structure with several of the top-level properties constituting nested objects.

The top level contains attributes and properties objects, and each edge of a call has metrics for both directions of the media stream as well as properties and summarized metrics. Further information for these object-typed properties can be found on the Details: Call Summary page.

Whether a particular edge is 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 a conceptual explanation.

Property nameTypePIIDescription
account_sidSID<AC>
Not PII

The unique SID identifier of the Account.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
call_sidSID<CA>
Not PII

The unique SID identifier of the Call.

Pattern: ^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34
call_typeenum<string>
Not PII

The Call Type of the summarized Call. One of carrier, sip, trunking or client.

Possible values:
carriersiptrunkingclient
call_stateenum<string>
Not PII

The Call State of the summarized Call. One of ringing, completed, busy, fail, noanswer, canceled, answered, undialed.

Possible values:
ringingcompletedbusyfailnoanswercanceledansweredundialed
answered_byenum<string>
Not PII

The Answered By value for the summarized call based on Answering Machine Detection (AMD). One of unknown, machine_start, machine_end_beep, machine_end_silence, machine_end_other, human or fax. Refer to AMD for more detail.

Possible values:
unknownmachine_startmachine_end_beepmachine_end_silencemachine_end_otherhumanfax
processing_stateenum<string>
Not PII

The Processing State of the Call Summary. The Processing State will be partial until the assembly of the Call Summary finishes, which occurs approximately 30 minutes after Call end. Then the Processing State changes to complete

Possible values:
completepartial
created_timestring<date-time>
Not PII

The time at which the Call was created, given in ISO 8601 format. Can be different from start_time in the event of queueing due to CPS

start_timestring<date-time>
Not PII

The time at which the Call was started, given in ISO 8601 format.

end_timestring<date-time>
Not PII

The time at which the Call was ended, given in ISO 8601 format.

durationinteger
Not PII

Duration between when the call was initiated and the call was ended

connect_durationinteger
Not PII

Duration between when the call was answered and when it ended

fromobject
PII MTL: 30 days

The calling party.

toobject
PII MTL: 30 days

The called party.

carrier_edgeobject
Not PII

Contains metrics and properties for the Twilio media gateway of a PSTN call.

client_edgeobject
Not PII

Contains metrics and properties for the Twilio media gateway of a Client call.

sdk_edgeobject
Not PII

Contains metrics and properties for the SDK sensor library for Client calls.

sip_edgeobject
Not PII

Contains metrics and properties for the Twilio media gateway of a SIP Interface or Trunking call.

tagsarray[string]
Not PII

Tags applied to calls by Voice Insights analysis indicating a condition that could result in subjective degradation of the call quality.

urlstring<uri>
Not PII

The URL of this resource.

attributesobject
Not PII

Attributes capturing call-flow-specific details.

propertiesobject
Not PII

Contains edge-agnostic call-level details.

trustobject
Not PII

Contains trusted communications details including Branded Call and verified caller ID.

annotationobject
Not PII

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.

Fetch a Summary resource

fetch-a-summary-resource page anchor
GET https://insights.twilio.com/v1/Voice/{CallSid}/Summary

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
CallSidSID<CA>required
Not PII

The unique SID identifier of the Call.

Pattern: ^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
ProcessingStateenum<string>Optional
Not PII

The Processing State of this Call Summary. One of complete, partial or all.

Possible values:
completepartial

Fetch a Call Summary

fetch-a-call-summary page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19
// Find your Account SID and Auth Token at twilio.com/console
_19
// and set the environment variables. See http://twil.io/secure
_19
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19
const authToken = process.env.TWILIO_AUTH_TOKEN;
_19
const client = twilio(accountSid, authToken);
_19
_19
async function fetchSummary() {
_19
const summary = await client.insights.v1
_19
.calls("CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
_19
.summary()
_19
.fetch();
_19
_19
console.log(summary.accountSid);
_19
}
_19
_19
fetchSummary();

Output

_39
{
_39
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_39
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_39
"call_type": "carrier",
_39
"call_state": "ringing",
_39
"answered_by": "machine_start",
_39
"processing_state": "complete",
_39
"created_time": "2015-07-30T20:00:00Z",
_39
"start_time": "2015-07-30T20:00:00Z",
_39
"end_time": "2015-07-30T20:00:00Z",
_39
"duration": 100,
_39
"connect_duration": 99,
_39
"from": {},
_39
"to": {},
_39
"carrier_edge": {},
_39
"client_edge": {},
_39
"sdk_edge": {},
_39
"sip_edge": {},
_39
"tags": [
_39
"tags"
_39
],
_39
"attributes": {},
_39
"properties": {},
_39
"trust": {},
_39
"annotation": {
_39
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_39
"call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_39
"answered_by": "human",
_39
"connectivity_issue": "invalid_number",
_39
"quality_issues": [
_39
"low_volume"
_39
],
_39
"spam": true,
_39
"call_score": 2,
_39
"comment": "this is a call",
_39
"incident": "https://twilio.zendesk.com/support/tickets/17353089"
_39
},
_39
"url": "https://insights.twilio.com/v1/Voice/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Summary"
_39
}

Fetch a partial Call Summary

fetch-a-partial-call-summary page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19
// Find your Account SID and Auth Token at twilio.com/console
_19
// and set the environment variables. See http://twil.io/secure
_19
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19
const authToken = process.env.TWILIO_AUTH_TOKEN;
_19
const client = twilio(accountSid, authToken);
_19
_19
async function fetchSummary() {
_19
const summary = await client.insights.v1
_19
.calls("CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
_19
.summary()
_19
.fetch({ processingState: "partial" });
_19
_19
console.log(summary.accountSid);
_19
}
_19
_19
fetchSummary();

Output

_39
{
_39
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_39
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_39
"call_type": "carrier",
_39
"call_state": "ringing",
_39
"answered_by": "machine_start",
_39
"processing_state": "partial",
_39
"created_time": "2015-07-30T20:00:00Z",
_39
"start_time": "2015-07-30T20:00:00Z",
_39
"end_time": "2015-07-30T20:00:00Z",
_39
"duration": 100,
_39
"connect_duration": 99,
_39
"from": {},
_39
"to": {},
_39
"carrier_edge": {},
_39
"client_edge": {},
_39
"sdk_edge": {},
_39
"sip_edge": {},
_39
"tags": [
_39
"tags"
_39
],
_39
"attributes": {},
_39
"properties": {},
_39
"trust": {},
_39
"annotation": {
_39
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_39
"call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_39
"answered_by": "human",
_39
"connectivity_issue": "invalid_number",
_39
"quality_issues": [
_39
"low_volume"
_39
],
_39
"spam": true,
_39
"call_score": 2,
_39
"comment": "this is a call",
_39
"incident": "https://twilio.zendesk.com/support/tickets/17353089"
_39
},
_39
"url": "https://insights.twilio.com/v1/Voice/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Summary"
_39
}

Rate this page: