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:

PropertyDescription
QualityScore1 to 5 quality score where 1 represents imperfect experience and 5 represents a perfect call.
IssueA 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.

IssueDescription
imperfect-audioImperfect audio quality: Choppy, echoed, or garbled audio during conversation.
dropped-callDropped call: call initially connected but was dropped.
incorrect-caller-idIncorrect caller ID: Call connected but caller ID displayed ‘Unknown’ or an incorrect number.
post-dial-delayPost dial delay: Call connected but there was a long delay between dialing the phone number and the start of ringing.
digits-not-capturedDTMF tones not captured: Failed to capture digit input on phone menus.
unsolicited-callUnsolicited call: Received telemarketer, wrong number, automated or other type of unsolicited call.
audio-latencyAudio latency: Call participants can hear each other but with significant audio delay.
one-way-audioOne 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:

ParameterDescription
QualityScoreAn 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:

ParameterDescription
IssueOne 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:

ParameterDescription
StartDateOnly include usage that has occurred on or after this date. Format is YYYY-MM-DD. All dates are in UTC.
EndDateOnly include usage that has occurred on or before this date. Format is YYYY-MM-DD. All dates are in UTC.
IncludeSubaccountstrue 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.

ParameterDescription
StatusCallbackThe URL that Twilio will request when the Feedback Summary is completed.
StatusCallbackMethodThe 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:

ParameterDescription
AccountSidYour Twilio account id. It is 34 characters long, and always starts with the letters AC.
FeedbackSummarySidThe unique id of the Feedback Summary.
StatusThe status of the Feedback Summary; queued, in-progress, completed, or failed.
ResourceUriThe 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:

ParameterDescription
StartDateThe first date for which feedback entries are included in this Feedback Summary, formatted as YYYY-MM-DD. All dates are in UTC.
EndDateThe last date for which feedback entries are included in this Feedback Summary, formatted as YYYY-MM-DD. All dates are in UTC.
AccountSidThe Account that reported the feedback entry.
IncludeSubaccountstrue if the feedback summary includes subaccounts, false otherwise.
StatusThe status of the feedback summary can be queued, in-progress, completed, or failed.
CallCountThe total number of calls.
CallFeedbackCountThe total number of calls with a feedback entry.
QualityScoreAverageThe average QualityScore of the feedback entries.
QualityScoreMedianThe median QualityScore of the feedback entries.
QualityScoreStandardDeviationThe standard deviation of the quality scores.
IssuesA 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