Get Started

REST API: Call Quality Feedback

The Call Feedback subresource provides a simple API to report the quality experienced during a phone call. On one hand, if the call was perfect your users can rate it with a Quality Score of 5. On the other hand, if the user experienced an issue, they can rate it with a lower Quality Score and specify the issue experienced, such as diminished audio quality, call dropped or incorrect caller id.

This makes it easy to build to feedback interfaces integrated into your application when the call is over like the example below:

Call Quality UI

Call Feedback Instance Resource

Feedback is a subresource of a Call instance resource. It represents a call quality feedback entry for a given phone call.

Resource URI

/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Feedback

Resource Properties

A Call Feedback instance resource is represented by the following properties:

Property Description
QualityScore 1 to 5 quality score where 1 represents imperfect experience and 5 represents a perfect call.
Issue A list of issues experienced during the call. The issues can be: imperfect-audio, dropped-call, incorrect-caller-id, post-dial-delay, digits-not-captured, audio-latency, or one-way-audio.
Issue Values

The following are the possible values for the 'Issue' parameter.

Issue Description
imperfect-audio Imperfect audio quality: Choppy, echoed, or garbled audio during conversation.
dropped-call Dropped call: call initially connected but was dropped.
incorrect-caller-id Incorrect caller ID: Call connected but caller ID displayed ‘Unknown’ or an incorrect number.
post-dial-delay Post dial delay: Call connected but there was a long delay between dialing the phone number and the start of ringing.
digits-not-captured DTMF tones not captured: Failed to capture digit input on phone menus.
unsolicited-call Unsolicited call: Received telemarketer, wrong number, automated or other type of unsolicited call.
audio-latency Audio latency: Call participants can hear each other but with significant audio delay.
one-way-audio One way audio: Only one party could hear the audio during the conversation.

HTTP GET

Returns the Feedback entry for a call identified by {CallSid}.

Example

HTTP POST

The POST request creates or updates a feedback entry for a Call. Every feedback entry needs a quality score and can optionally have one or multiple issues. if successful, it returns the resource representation identical to that returned above when making a GET Request.

Required Parameters

You must include the following parameter in your POST request:

Parameter Description
QualityScore An integer 1 to 5 quality score where 1 represents very poor call quality and 5 represents a perfect call.
Optional Parameters

You may include the following parameter in your POST request:

Parameter Description
Issue One or more issues experienced during the call. The issues can be: imperfect-audio, dropped-call, incorrect-caller-id, post-dial-delay, digits-not-captured, audio-latency, or one-way-audio.
Example

Create a new Feedback entry for a given call.

HTTP PUT

Not supported

HTTP DELETE

Not supported

Call Feedback Summary List Resource

With Feedback Summaries you can get a pulse of your end user’s perception of quality and the most common issues encountered in the context of all your voice traffic for a range of dates.

HTTP POST

With Feedback Summaries you can get a pulse of your end user’s perception of quality and the most common issues encountered in the context of all your voice traffic for a range of dates.

POST /2010-04-01/Accounts/{AccountSid}/Calls/FeedbackSummary

You must POST at least the following to create a new Feedback Summary:

Parameter Description
StartDate Only include usage that has occurred on or after this date. Format is YYYY-MM-DD. All dates are in UTC.
EndDate Only include usage that has occurred on or before this date. Format is YYYY-MM-DD. All dates are in UTC.
IncludeSubaccounts true to include feedback entries for the master account and all subaccounts. false to include feedback entries for the specified account. IncludeSubaccounts is false by default.

You may also set the a StatusCallback URL to get a webhook when the Feedback Summary is completed.

Parameter Description
StatusCallback The URL that Twilio will request when the Feedback Summary is completed.
StatusCallbackMethod The HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST.
StatusCallback Parameter

After the Feedback Summary is completed, Twilio will make an asynchronous HTTP request to the StatusCallback URL if you provided one in your POST.

Request Parameters

The parameters Twilio passes to your application in its asynchronous request to the StatusCallback URL include the parameters specified below:

Parameter Description
AccountSid Your Twilio account id. It is 34 characters long, and always starts with the letters AC.
FeedbackSummarySid The unique id of the Feedback Summary.
Status The status of the Feedback Summary; queued, in-progress, completed, or failed.
ResourceUri The Feedback Summary Resource URI.

For example, you might request a Feedback Summary for the month of January, 2014 for the master account and all subaccounts. In this case, the query string would be StartDate=2014-02-01&EndDate=2014-02-31&IncludeSubaccounts=true. This would request a Feedback Summary for all feedback entries for calls made during January. See Example below.

Example

Create a new FeedbackSummary

Call Feedback Summary Instance Resource

Returns FeedbackSummary that was previously requested.

Resource URI

/2010-04-01/Accounts/{AccountSid}/Calls/FeedbackSummary/{FeedbackSummarySid}

Resource Properties

A Feedback Summary instance resource is represented by the following properties:

Parameter Description
StartDate The first date for which feedback entries are included in this Feedback Summary, formatted as YYYY-MM-DD. All dates are in UTC.
EndDate The last date for which feedback entries are included in this Feedback Summary, formatted as YYYY-MM-DD. All dates are in UTC.
AccountSid The Account that reported the feedback entry.
IncludeSubaccounts true if the feedback summary includes subaccounts, false otherwise.
Status The status of the feedback summary can be queued, in-progress, completed, or failed.
CallCount The total number of calls.
CallFeedbackCount The total number of calls with a feedback entry.
QualityScoreAverage The average QualityScore of the feedback entries.
QualityScoreMedian The median QualityScore of the feedback entries.
QualityScoreStandardDeviation The standard deviation of the quality scores.
Issues A list of all the issues experienced. The list includes the issue name, the number of occurrences and percentage of calls that experienced this issue.

HTTP GET

Returns a representation of the Feedback Summary identified by {FeedbackSummarySid}.

Example 1

Return the FeedbackSummary entry

Example 2

Return the FeedbackSummary entry when in-progress

HTTP DELETE

Deletes a Feedback Summary.

If successful, Twilio will return an HTTP 204 response with no body.

DELETE /2010-04-01/Accounts/{AccountSid}/Calls/FeedbackSummary/{FeedbackSummarySid}
Example

Delete the FeedbackSummary entry