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

Call Annotation Resource


(warning)

Warning

Currently the Call Annotation API is only available for the United States (US1) Region. Find more information on the Twilio Regional Product and Feature Availability page.

A Call Annotation captures subjective experience details for a voice call.

For instance, a Call Annotation can contain information about

  • call quality issues,
  • spam labeling,
  • customer-internal tags, and
  • other meta data.

Using the Call Annotation Resource, you can

for a specific call.

To get a list of Call Summaries with specific Call Annotations, you can use the Call Summaries Resource.


Annotation Properties

annotation-properties page anchor
Resource properties
call_sidtype: SID<CA>Not PII

The unique SID identifier of the Call.


account_sidtype: SID<AC>Not PII

The unique SID identifier of the Account.


answered_bytype: enum<STRING>Not PII

Specifies which entity answered the call as determined by Answering Machine Detection. Possible enumerated values, one of: human, machine. human indicates the call was answered by a person. machine indicates the call was answered by an answering machine.

Possible values:
unknown_answered_byhumanmachine

connectivity_issuetype: enum<STRING>Not PII

Specifies if the call had any connectivity issues. One of no_connectivity_issue, invalid_number, caller_id, dropped_call, or number_reachability.

Possible values:
unknown_connectivity_issueno_connectivity_issueinvalid_numbercaller_iddropped_callnumber_reachability

quality_issuestype: string[]Not PII

Specifies if the call had any subjective quality issues. Possible values are one or more of no_quality_issue, low_volume, choppy_robotic, echo, dtmf, latency, owa, or static_noise.


spamtype: booleanNot PII

Specifies if the call was a spam call. Use this to provide feedback on whether calls placed from your account were marked as spam, or if inbound calls received by your account were unwanted spam. Is of type Boolean: true, false. Use true if the call was a spam call.


call_scoretype: integerNot PII

Specifies the Call Score, if available. This is of type integer. Use a range of 1-5 to indicate the call experience score, with the following mapping as a reference for rating the call [5: Excellent, 4: Good, 3 : Fair, 2 : Poor, 1: Bad].


commenttype: stringNot PII

Specifies any comments pertaining to the call. Twilio does not treat this field as PII, so no PII should be included in comments.


incidenttype: stringNot PII

Incident or support ticket associated with this call. The incident property is of type string with a maximum character limit of 100. Twilio does not treat this field as PII, so no PII should be included in incident.


urltype: string<URI>Not PII

Get the Call Annotation for a specific Call

get-the-call-annotation-for-a-specific-call page anchor
GET https://insights.twilio.com/v1/Voice/{CallSid}/Annotation

Parameters

fetch-parameters page anchor
URI parameters
CallSidtype: SID<CA>Not PII
Path Parameter

The unique SID identifier of the Call.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.insights.v1.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.annotation()
_11
.fetch()
_11
.then(annotation => console.log(annotation.callSid));

Output

_14
{
_14
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_14
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_14
"answered_by": "human",
_14
"connectivity_issue": "invalid_number",
_14
"quality_issues": [
_14
"low_volume"
_14
],
_14
"spam": true,
_14
"call_score": 2,
_14
"comment": "this is a call",
_14
"incident": "https://twilio.zendesk.com/support/tickets/17353089",
_14
"url": "https://insights.twilio.com/v1/Voice/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Annotation"
_14
}


Update the Call Annotation for a specific Call

update-the-call-annotation-for-a-specific-call page anchor
POST https://insights.twilio.com/v1/Voice/{CallSid}/Annotation

(information)

Info

Call Annotations can be updated as long as the Call Summary record is addressable via the API.

URI parameters
CallSidtype: SID<CA>Not PII
Path Parameter

The unique string that Twilio created to identify this Call resource. It always starts with a CA.


Request body parameters
AnsweredBytype: enum<STRING>Not PII

Specify which entity answered the call as determined by Answering Machine Detection. Use this to provide feedback on Answering Machine Detection accuracy. Possible enumerated values, one of: human, machine. human indicates the call was answered by a person. machine indicates the call was answered by an answering machine.

Possible values:
unknown_answered_byhumanmachine

ConnectivityIssuetype: enum<STRING>Not PII

Specify if the call had any connectivity issues. Possible enumerated values, one of no_connectivity_issue, invalid_number, caller_id, dropped_call, or number_reachability.

Possible values:
unknown_connectivity_issueno_connectivity_issueinvalid_numbercaller_iddropped_callnumber_reachability

QualityIssuestype: stringNot PII

Specify if the call had any subjective quality issues. Possible values, one or more of no_quality_issue, low_volume, choppy_robotic, echo, dtmf, latency, owa, static_noise. Use comma separated values to indicate multiple quality issues for the same call.


Spamtype: booleanNot PII

A boolean flag to indicate if the call was a spam call. Use this to provide feedback on whether calls placed from your account were marked as spam, or if inbound calls received by your account were unwanted spam. Use true if the call was a spam call.


CallScoretype: integerNot PII

Specify the call score. This is of type integer. Use a range of 1-5 to indicate the call experience score, with the following mapping as a reference for rating the call [5: Excellent, 4: Good, 3 : Fair, 2 : Poor, 1: Bad].


Commenttype: stringNot PII

Specify any comments pertaining to the call. comment has a maximum character limit of 100. Twilio does not treat this field as PII, so no PII should be included in the comment.


Incidenttype: stringNot PII

Associate this call with an incident or support ticket. The incident parameter is of type string with a maximum character limit of 100. Twilio does not treat this field as PII, so no PII should be included in incident.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.insights.v1.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.annotation()
_11
.update({answeredBy: 'human'})
_11
.then(annotation => console.log(annotation.callSid));

Output

_15
{
_15
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_15
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_15
"answered_by": "human",
_15
"connectivity_issue": "invalid_number",
_15
"quality_issues": [
_15
"low_volume",
_15
"choppy_robotic"
_15
],
_15
"spam": true,
_15
"call_score": 2,
_15
"comment": "this is a call",
_15
"incident": "https://twilio.zendesk.com/support/tickets/17353089",
_15
"url": "https://insights.twilio.com/v1/Voice/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Annotation"
_15
}


Rate this page: