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
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.
The unique SID identifier of the Call.
^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34The unique SID identifier of the Account.
^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34Specifies 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.
unknown_answered_byhumanmachineSpecifies if the call had any connectivity issues. One of no_connectivity_issue, invalid_number, caller_id, dropped_call, or number_reachability.
unknown_connectivity_issueno_connectivity_issueinvalid_numbercaller_iddropped_callnumber_reachabilitySpecifies 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.
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.
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].
Specifies any comments pertaining to the call. Twilio does not treat this field as PII, so no PII should be included in comments.
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.
GET https://insights.twilio.com/v1/Voice/{CallSid}/Annotation
The unique SID identifier of the Call.
^CA[0-9a-fA-F]{32}$Min length: 34Max length: 341// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchAnnotation() {11const annotation = await client.insights.v112.calls("CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.annotation()14.fetch();1516console.log(annotation.callSid);17}1819fetchAnnotation();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",4"answered_by": "human",5"connectivity_issue": "invalid_number",6"quality_issues": [7"low_volume"8],9"spam": true,10"call_score": 2,11"comment": "this is a call",12"incident": "https://twilio.zendesk.com/support/tickets/17353089",13"url": "https://insights.twilio.com/v1/Voice/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Annotation"14}
POST https://insights.twilio.com/v1/Voice/{CallSid}/Annotation
Call Annotations can be updated as long as the Call Summary record is addressable via the API.
The unique string that Twilio created to identify this Call resource. It always starts with a CA.
^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34application/x-www-form-urlencodedSpecify 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.
unknown_answered_byhumanmachineSpecify if the call had any connectivity issues. Possible enumerated values, one of no_connectivity_issue, invalid_number, caller_id, dropped_call, or number_reachability.
unknown_connectivity_issueno_connectivity_issueinvalid_numbercaller_iddropped_callnumber_reachabilitySpecify 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.
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.
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].
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.
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateAnnotation() {11const annotation = await client.insights.v112.calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.annotation()14.update({ answeredBy: "human" });1516console.log(annotation.callSid);17}1819updateAnnotation();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"answered_by": "human",5"connectivity_issue": "invalid_number",6"quality_issues": [7"low_volume",8"choppy_robotic"9],10"spam": true,11"call_score": 2,12"comment": "this is a call",13"incident": "https://twilio.zendesk.com/support/tickets/17353089",14"url": "https://insights.twilio.com/v1/Voice/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Annotation"15}