Menu

Expand
Rate this page:

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

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.

Example 1
Loading Code Sample...
        
        

        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...
              
              

              Update a Comment

              Rate this page:

              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.

              Loading Code Sample...
                    
                    
                    

                    Thank you for your feedback!

                    Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                    Sending your feedback...
                    🎉 Thank you for your feedback!
                    Something went wrong. Please try again.

                    Thanks for your feedback!

                    thanks-feedback-gif