Using APIs for analytics

This section describes the API operations that you use to retrieve analytics for a bot.

Filtering results

The Analytics API requests require you to specify the startTime and endTime. The API returns sessions, intents, intent stages, or utterances that began after the startTime and ended before the endTime.

filters is an optional field in the Analytics API requests. It maps to a list of AnalyticsSessionFilter, AnalyticsIntentFilter, AnalyticsIntentStageFilter, or AnalyticsUtteranceFilter objects. In each object, use the fields to create an expression to filter by. For example, if you add the following filter to the list, the bot searches for conversations that are longer than 30 seconds.

{
    "name": "Duration",
    "operator": "GT",
    "value": "30 sec",
}

Retrieving metrics for a bot

Use the ListSessionMetrics, ListIntentMetrics, ListIntentStageMetrics, and ListUtteranceMetrics operations to retrieve summary metrics for sessions, intents, intent stages, and utterances.

For these operations, fill in the following required fields:

The remaining fields in the request are optional. You can filter and organize the results in the following ways:

Use the following fields to handle the display of the response:

If you are using ListUtteranceMetrics, you can specify attributes to return in the attributes field. This field maps to a list containing a single AnalyticsUtteranceAttribute object. Specify LastUsedIntent in the name field to return the intent that Amazon Lex V2 is using at the time of the utterance.

In the response, the results field maps to a list of AnalyticsSessionResult, AnalyticsIntentResult, AnalyticsIntentStageResult, or AnalyticsUtteranceResult objects. Each object contains a metrics field which returns the value of a summary statistic for a metric that you requested, in addition to any bins or groups created from the methods you specified.

Retrieving metadata for sessions and utterances in a bot

Use the ListSessionAnalyticsData and ListUtteranceAnalyticsData operations to retrieve metadata about individual sessions and utterances.

Fill in the required startTime and endTime fields to define a time range for which you want to retrieve results.

The remaining fields in the request are optional. To filter and sort results:

Use the following fields to handle the display of the response:

In the response, the sessions or utterances field maps to a list of SessionSpecification or UtteranceSpecification objects. Each object contains metadata for a single session or utterance.

Retrieving metadata for sessions and utterances in a bot

Use the ListIntentPaths operation to retrieve metrics about an order of intents that customers take in conversation with a bot.

For this operation, fill in the following required fields:

Use the optional filters field to filter the results. For more details, see Filtering results.

Viewing utterance statistics from Lex V2 conversations

You can use utterance statistics to determine the utterances that your users are sending to your bot. You can see both the utterances that Amazon Lex V2 successfully detects and the utterances that it doesn't. You can use this information to help tune your bot.

For example, if you find that your users are sending an utterance that Amazon Lex V2 is missing, you can add the utterance to an intent. The Draft version of the intent is updated with the new utterance and you can test it before deploying it to your bot.

An utterance is detected when Amazon Lex V2 recognizes the utterance as an attempt to invoke an intent configured for a bot. An utterance is missed when Amazon Lex V2 doesn't recognize the utterance and invokes the AMAZON.FallbackIntent instead.

Utterance statistics can be viewed using the ListUtteranceMetrics API and the ListAggregatedUtterance API.

Utterance statistics are not generated using ListUtteranceMetrics API under the following conditions:

The ListUtteranceMetrics API provides additonal features including:

Utterance statistics are not generated using ListAggregatedUtterance API under the following conditions:

The ListAggregatedUtterance API provides features including:

Using utterance statistics, you can see whether a specific utterance was detected or missed, alongside the last time that the utterance was used in a bot interaction.

Amazon Lex V2 stores utterances continuously while users interact with your bot. You can query the statistics using the console or the ListAggregatedUtterances operation. It has a data retention of 15 days and it is not available if the user has opted out of data storage. You can delete utterances using the DeleteUtterances operation or by opting out of data storage. All utterances are deleted if you close your AWS account. Stored utterances are encrypted with a server-managed key.

When you delete a bot version, utterance statistics are available for the version for up to 30 days with ListUtteranceMetrics, and 15 days using ListAggregatedUtterances. You can't see statistics for deleted version in the Amazon Lex V2 console. To see the statistics for deleted versions, you can use both ListAggregatedUtterances and ListUtteranceMetricsoperations.

With both the ListAggregatedUtterances and ListUtteranceMetrics APIs, utterances are aggregated by the text of the utterance. For example, all instances where the customer used the phrase "I want to order a pizza" are aggregated into the same line in a response. When you use the RecognizeUtterance operation, the text used is the input transcript.

To use the ListAggregatedUtterances and ListUtteranceMetrics APIs, apply the following policy to a role.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ListAggregatedUtterancesPolicy",
            "Effect": "Allow",
            "Action": "lex:ListAggregatedUtterances",
            "Resource": "*"
        }
    ]
}