Use the End of Call Survey to collect user feedback

• Node.js active Long Term Support(LTS) versions are recommended.

Sample of API usage

The End of Call Survey feature should be used after the call ends. Users can rate any kind of VoIP call, 1:1, group, meeting, outgoing and incoming. Once a user's call ends, your application can show a UI to the end user allowing them to choose a rating score, and if needed, pick issues they’ve encountered during the call from our predefined list.

The following code snips show an example of one-to-one call. After the end of the call, your application can show a survey UI and once the user chooses a rating, your application should call the feature API to submit the survey with the user choices.

We encourage you to use the default rating scale. However, you can submit a survey with custom rating scale. You can check out the sample application for the sample API usage.

Rate call only - no custom scale

call.feature(Features.CallSurvey).submitSurvey({
    overallRating: { score: 5 }, // issues are optional
}).then(() => console.log('survey submitted successfully'));

OverallRating is a required category for all surveys.

Rate call only - with custom scale and issues

call.feature(Features.CallSurvey).submitSurvey({
    overallRating: {
        score: 1, // my score
        scale: { // my custom scale
            lowerBound: 0,
            upperBound: 1,
            lowScoreThreshold: 0
        },
        issues: ['HadToRejoin'] // my issues, check the table below for all available issues
    }
}).then(() => console.log('survey submitted successfully'));

Rate overall, audio, and video with a sample issue

call.feature(Features.CallSurvey).submitSurvey({
    overallRating: { score: 3 },
    audioRating: { score: 4 },
    videoRating: { score: 3, issues: ['Freezes'] }
}).then(() => console.log('survey submitted successfully'))

Handle errors the SDK can send

call.feature(Features.CallSurvey).submitSurvey({
    overallRating: { score: 3 }
}).catch((e) => console.log('error when submitting survey: ' + e))

Find different types of errors

Failures while submitting survey

The API returns the following error messages if data validation fails or the survey can't be submitted.

• At least one survey rating is required.

• In default scale X should be 1 to 5. - where X is either of:

  • overallRating.score
  • audioRating.score
  • videoRating.score
  • ScreenshareRating.score

• {propertyName}: {rating.score} should be between {rating.scale?.lowerBound} and {rating.scale?.upperBound}.

• {propertyName}: {rating.scale?.lowScoreThreshold} should be between {rating.scale?.lowerBound} and {rating.scale?.upperBound}.

• {propertyName} lowerBound: {rating.scale?.lowerBound} and upperBound: {rating.scale?.upperBound} should be between 0 and 100.

• Please try again [ACS failed to submit survey, due to network or other error].

We'll return any error codes with a message.

• Error code 400 (bad request) for all the error messages except one.

{ message: validationErrorMessage, code: 400 }

• One 408 (timeout) when event discarded:

{ message: "Please try again.", code: 408 }

All possible values

Default survey API configuration

More survey tags

Customization options

You can choose to collect each of the four API values or only the ones you find most important. For example, you can choose to only ask customers about their overall call experience instead of asking them about their audio, video, and screen share experience. You can also customize input ranges to suit your needs. The default input range is 1 to 5 for Overall Call, Audio, Video, and Screenshare. However, each API value can be customized from a minimum of 0 to maximum of 100.

Customization examples

Custom questions

In addition to using the End of Call Survey API, you can create your own survey questions and incorporate them with the End of Call Survey results. Below you find steps to incorporate your own customer questions into a survey and query the results of the End of Call Survey API and your own survey questions.

• Create App Insight resource.

• Embed Azure AppInsights into your application Click here to know more about App Insight initialization using plain JavaScript. Alternatively, you can use NPM to get the App Insights dependences. Click here to know more about App Insight initialization using NPM.

• Build a UI in your application that serves custom questions to the user and gather their input, lets assume that your application gathered responses as a string in the improvementSuggestion variable

• Submit survey results to ACS and send user response using App Insights:

  currentCall.feature(SDK.Features.CallSurvey).submitSurvey(survey).then(res => {
  // `improvementSuggesstion` contains custom, user response
      if (improvementSuggestion !== '') {
          appInsights.trackEvent({
                  name: "CallSurvey", properties: {
                      // Survey ID to correlate the survey
                      id: res.id,
                      // Other custom properties as key value pair
                      improvementSuggestion: improvementSuggestion
                  }
              });
       }
  });
  appInsights.flush();
  

User responses that were sent using AppInsights are available under your App Insights workspace. You can use Workbooks to query between multiple resources, correlate call ratings and custom survey data. Steps to correlate the call ratings and custom survey data:

• Create new Workbooks (Your ACS Resource -> Monitoring -> Workbooks -> New) and query Call Survey data from your ACS resource.
• Add new query (+Add -> Add query)
• Make sure Data source is Logs and Resource type is Communication
• You can rename the query (Advanced Settings -> Step name [example: call-survey])
• Be aware that it could require a maximum of 2 hours before the survey data becomes visible in the Azure portal. Query the call rating data-

  ACSCallSurvey
  | where TimeGenerated > now(-24h)
  

• Add another query to get data from App Insights (+Add -> Add query)
• Make sure Data source is Logs and Resource type is Application Insights
• Query the custom events-

  customEvents
  | where timestamp > now(-24h)
  | where name == 'CallSurvey'
  | extend d=parse_json(customDimensions)
  | project SurveyId = d.id, ImprovementSuggestion = d.improvementSuggestion
  

• You can rename the query (Advanced Settings -> Step name [example: custom-call-survey])
• Finally merge these two queries by surveyId. Create new query (+Add -> Add query).
• Make sure the Data source is Merge and select Merge type as needed

title: Azure Communication Services End of Call Survey titleSuffix: An Azure Communication Services tutorial document description: Learn how to use the End of Call Survey to collect user feedback. author: viniciusl-msft ms.author: viniciusl manager: gaobob services: azure-communication-services ms.date: 7/30/2024 ms.topic: tutorial ms.service: azure-communication-services ms.subservice: calling

Sample of API usage

The End of Call Survey feature should be used after the call ends. Users can rate any kind of VoIP call, 1:1, group, meeting, outgoing and incoming. Once a user's call ends, your application can show a UI to the end user allowing them to choose a rating score, and if needed, pick issues they’ve encountered during the call from our predefined list.

The following code snips show an example of one-to-one call. After the end of the call, your application can show a survey UI and once the user chooses a rating, your application should call the feature API to submit the survey with the user choices.

We encourage you to use the default rating scale, which is the five star rating (between 1-5). However, you can submit a survey with custom rating scale.

Start a survey

You create a CallSurvey object by starting a survey. This records a survey intent. In case this particular CallSurvey object isn't submitted afterwards, it means that the survey was skipped or ignored by the end customer.

SurveyCallFeature surveyCallFeature = call.feature(Features.SURVEY);
try {
    CallSurvey survey = surveyCallFeature.startSurvey().get();
} catch (InterruptedException | ExecutionException e) {
    // failure to start survey
}

General usage

When rating calls, you must respect values defined on the scale field. The lowerBound value denotes the worst experience possible, while the upperBound value means the perfect experience. Both values are inclusive.

OverallRating is a required category for all surveys.

For more information on suggested survey use, see Survey Concepts

Rate call only - no custom scale

SurveyScore overall = new SurveyScore();
overall.setScore(5);
callSurvey.setOverallScore(overall);

Rate call only - with custom scale and issues

// configuring scale
CallSurveyRatingScale ratingScale = new CallSurveyRatingScale();
ratingScale.setLowerBound(0);
ratingScale.setLowerBound(1);
ratingScale.setLowScoreThreshold(0);
SurveyScore overall = new SurveyScore();
overall.setScale(ratingScale);

// setting score according to scale
overall.setScore(1);
callSurvey.setOverallScore(overall);
// reporting one or more issues
callSurvey.setCallIssues(CallIssues.HAD_TO_REJOIN);

Rate overall, audio, and video with a sample issue

SurveyScore overall = new SurveyScore();
overall.setScore(3);
SurveyScore audio = new SurveyScore();
audio.setScore(4);
SurveyScore video = new SurveyScore();
video.setScore(3);
callSurvey.setOverallScore(overall);
callSurvey.setAudioScore(audio);
callSurvey.setVideoScore(video);
callSurvey.setVideoIssues(VideoIssues.FREEZES);

Submit Survey and handle errors the SDK can send

try {
    CallSurveyResult survey = surveyCallFeature.submitSurvey(survey).get();
} catch (InterruptedException e) {
    // Threading error
} catch (ExecutionException e) {
    Log.e("SURVEY", e.getCause().getMessage());
}

Find different types of errors

Failures while submitting survey:

The submitSurvey API can return an error in the following scenarios:

• Overall survey rating is required.

• CallSurveyRatingScale bounds must be within 0 and 100. LowerBound should be less than UpperBound. LowScoreThreshold should be within bounds.

• Any of the scores must respect the bounds defined by the CallSurveyRatingScale. All values in the CallSurveyRatingScale object are inclusive. Using the default scale, the score value should be between 1 and 5.

• Survey can't be submitted because of network/service error.

Available survey tags

Overall call

Audio issues

Video issues

Screen share issues

Customization options

You can choose to collect each of the four API values or only the ones you find most important. For example, you can choose to only ask customers about their overall call experience instead of asking them about their audio, video, and screen share experience. You can also customize input ranges to suit your needs. The default input range is 1 to 5 for Overall Call, Audio, Video, and Screen share. However, each API value can be customized from a minimum of 0 to maximum of 100.

Custom questions

In addition to using the End of Call Survey API, you can create your own survey questions and incorporate them with the End of Call Survey results.

The result payload of SubmitSurvey operation provides data that you can use to correlate ACS Survey data with your own custom data and storage. CallSurveyResult class have the SurveyId field that denotes a unique identifier for the survey and CallId denotes an identifier for the call where the survey was generated. Saving these identifiers along with your customized data allow data to be associated uniquely.

Sample of API usage

The End of Call Survey feature should be used after the call ends. Users can rate any kind of VoIP call, 1:1, group, meeting, outgoing and incoming. Once a user's call ends, your application can show a UI to the end user allowing them to choose a rating score, and if needed, pick issues they’ve encountered during the call from our predefined list.

The following code snips show an example of one-to-one call. After the end of the call, your application can show a survey UI and once the user chooses a rating, your application should call the feature API to submit the survey with the user choices.

We encourage you to use the default rating scale, which is the five star rating (between 1-5). However, you can submit a survey with custom rating scale.

Start a survey

You create a CallSurvey object by starting a survey. This records a survey intent. In case this particular CallSurvey object isn't submitted afterwards, it means that the survey was skipped or ignored by the end customer.

var surveyCallFeature = self.call.feature(Features.survey)
do {
    try self.callSurvey = await surveyFeature.startSurvey()
} catch {
    print("Failure to start survey")
}

General usage

When rating calls, you must respect values defined on the scale field. The lowerBound value denotes the worst experience possible, while the upperBound value means the perfect experience. Both values are inclusive.

OverallRating is a required category for all surveys.

For more information on suggested survey use, see Survey Concepts

Rate call only - no custom scale

let overallScore = SurveyScore()
overallScore.score = Int32(5)
callSurvey.overallScore = overallScore

Rate call only - with custom scale and issues

// configuring scale
var ratingScale = new CallSurveyRatingScale()
ratingScale.lowerBound = 0;
ratingScale.upperBound = 1;
ratingScale.lowScoreThreshold = 0;
SurveyScore overall = new SurveyScore();
overall.scale = ratingScale;
// setting score according to scale
overall.score = 1;

callSurvey.overallScore = overall;

// reporting one or more issues
callSurvey.callIssues = [ CallIssues.hadToRejoin ];

Rate overall, audio, and video with a sample issue

let overall = SurveyScore();
overall.score  = 3;

let audio = SurveyScore();
audio.score = 4;

let video = SurveyScore();
video.score = 3;

callSurvey.overallScore = overall;
callSurvey.audioScore = audio;
callSurvey.videoScore = video;
callSurvey.videoIssues = [ VideoIssues.freezes ];

Submit Survey and handle errors the SDK can send

do {
    var result =  try await self.surveyFeature!.submit(survey: callSurvey)
} catch let error as NSError {
    print("==> Survey Not Submitted " + error.localizedDescription)
}

Find different types of errors

Failures while submitting survey:

The submitSurvey API can return an error in the following scenarios:

• Overall survey rating is required.

• CallSurveyRatingScale bounds must be within 0 and 100. LowerBound should be less than UpperBound. LowScoreThreshold should be within bounds.

• Any of the scores must respect the bounds defined by the CallSurveyRatingScale. All values in the CallSurveyRatingScale object are inclusive. Using the default scale, the score value should be between 1 and 5.

• Survey can't be submitted because of network/service error.

Available Survey tags

Overall Call

Audio issues

Video issues

Screen share issues

Customization options

You can choose to collect each of the four API values or only the ones you find most important. For example, you can choose to only ask customers about their overall call experience instead of asking them about their audio, video, and screen share experience. You can also customize input ranges to suit your needs. The default input range is 1 to 5 for Overall Call, Audio, Video, and Screen share. However, each API value can be customized from a minimum of 0 to maximum of 100.

Custom questions

In addition to using the End of Call Survey API, you can create your own survey questions and incorporate them with the End of Call Survey results.

However, the result payload of SubmitSurvey operation provides data that you can use to correlate ACS Survey data with your own custom data and storage. CallSurveyResult class have the SurveyId field that denotes a unique identifier for the survey and CallId denotes an identifier for the call where the survey was generated. Saving these identifiers along with your customized data allows data to be associated uniquely.

Sample of API usage

The End of Call Survey feature should be used after the call ends. Users can rate any kind of VoIP call, 1:1, group, meeting, outgoing and incoming. Once a user's call ends, your application can show a UI to the end user allowing them to choose a rating score, and if needed, pick issues they’ve encountered during the call from our predefined list.

The following code snips show an example of one-to-one call. After the end of the call, your application can show a survey UI and once the user chooses a rating, your application should call the feature API to submit the survey with the user choices.

We encourage you to use the default rating scale, which is the five star rating (between 1-5). However, you can submit a survey with custom rating scale.

Start a survey

You create a CallSurvey object by starting a survey. This records a survey intent. In case this particular CallSurvey object isn't submitted afterwards, it means that the survey was skipped or ignored by the end customer.

var surveyCallFeature = call.Features.Survey;
var survey = await surveyCallFeature.StartSurveyAsync();

General usage

When rating calls, you must respect values defined on the scale field. The lowerBound value denotes the worst experience possible, while the upperBound value means the perfect experience. Both values are inclusive.

OverallRating is a required category for all surveys.

For more information on suggested survey use, see Survey Concepts

Rate call only - no custom scale

survey.OverallScore = new CallSurveyScore() { Score = 5 };

Rate call only - with custom scale and issues

// configuring scale and score
survey.OverallScore = new CallSurveyScore() { 
    Scale = new CallSurveyRatingScale() { 
                LowerBound = 0,
                UpperBound = 1,
                LowScoreThreshold = 1,
            }, 
            Score = 1 
};

// reporting one or more issues
survey.OverallIssues = CallIssues.HadToRejoin;

Rate overall, audio, and video with a sample issue

survey.OverallScore = new CallSurveyScore() { 
    Score = 5 
};
survey.AudioScore = new CallSurveyScore() { 
    Score = 4
};
survey.VideoScore = new CallSurveyScore() { 
    Score = 3
};

survey.videoIssues = VideoIssues.Freezes;

Submit Survey and handle errors the SDK can send

try
{
    CallSurveyResult result = await surveyCallFeature.SubmitSurveyAsync(survey);
    Console.WriteLine("Survey submitted" + result.SurveyId);
} catch (Exception ex)
{
   Console.WriteLine(ex.Message);
}

Find different types of errors

Failures while submitting survey:

The submitSurvey API can return an error in the following scenarios:

• Overall survey rating is required.

• CallSurveyRatingScale bounds must be within 0 and 100. LowerBound should be less than UpperBound. LowScoreThreshold should be within bounds.

• Any of the scores must respect the bounds defined by the CallSurveyRatingScale. All values in the CallSurveyRatingScale object are inclusive. Using the default scale, the score value should be between 1 and 5.

• Survey can't be submitted because of network/service error.

Available Survey tags

Overall Call

Audio Issues

Video Issues

Screen share Issues

Customization options

You can choose to collect each of the four API values or only the ones you find most important. For example, you can choose to only ask customers about their overall call experience instead of asking them about their audio, video, and screen share experience. You can also customize input ranges to suit your needs. The default input range is 1 to 5 for Overall Call, Audio, Video, and Screen share. However, each API value can be customized from a minimum of 0 to maximum of 100.

Custom questions

In addition to using the End of Call Survey API, you can create your own survey questions and incorporate them with the End of Call Survey results.

However, the result payload of SubmitSurvey operation provides data that you can use to correlate ACS Survey data with your own custom data and storage. CallSurveyResult class have the SurveyId field that denotes a unique identifier for the survey and CallId denotes an identifier for the call where the survey was generated. Saving these identifiers along with your customized data allow data to be associated uniquely.