Call Annotation Resource

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

get the Call Annotation, or
update the Call Annotation

for a specific call.

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

Annotation properties

Resource Properties in REST API format
`call_sid`	sid<CA> Not PII The unique SID identifier of the Call.
`account_sid`	sid<AC> Not PII The unique SID identifier of the Account.
`answered_by`	enum:answered_by 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.
`connectivity_issue`	enum:connectivity_issue Not PII Specifies if the call had any connectivity issues. One of `no_connectivity_issue`, `invalid_number`, `caller_id`, `dropped_call`, or `number_reachability`.
`quality_issues`	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`.
`spam`	boolean Not 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_score`	integer? Not 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].
`comment`	string Not PII Specifies any comments pertaining to the call. Twilio does not treat this field as PII, so no PII should be included in comments.
`incident`	string Not 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`.
`url`	url Not PII

Get the Call Annotation for a specific Call

get

https://insights.twilio.com/v1/Voice/{CallSid}/Annotation

Parameters

Parameters in REST API format
`call_sid` Path	get sid<CA> Not PII The unique SID identifier of the Call.

Parameters in REST API format

call_sid

Path

get sid<CA> Not PII

The unique SID identifier of the Call.

Example 1

Loading Code Sample...

Example JSON response

Get a Call Annotation

Update the Call Annotation for a specific Call

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.

Parameters

Parameters in REST API format
`call_sid` Path	post sid<CA> Not PII The unique string that Twilio created to identify this Call resource. It always starts with a CA.
`answered_by` Optional	post ienum:answered_by 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.
`connectivity_issue` Optional	post ienum:connectivity_issue 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`.
`quality_issues` Optional	post string Not 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.
`spam` Optional	post boolean Not 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.
`call_score` Optional	post integer? Not 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].
`comment` Optional	post string Not 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`.
`incident` Optional	post string Not 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`.

Example 1

Loading Code Sample...

Example JSON response

Update a Comment

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.

Annotation properties

Get the Call Annotation for a specific Call

Parameters

Example 1

Get a Call Annotation

Update the Call Annotation for a specific Call

Parameters

Example 1

Update a Comment

Need some help?

Thank you for your feedback!

Need help? Talk to Support

Thanks for your feedback!