ListAggregatedUtterances
Provides a list of utterances that users have sent to the bot.
Utterances are aggregated by the text of the utterance. For example, all instances where customers used the phrase "I want to order pizza" are aggregated into the same line in the response.
You can see both detected utterances and missed utterances. A detected utterance is where the bot properly recognized the utterance and activated the associated intent. A missed utterance was not recognized by the bot and didn't activate an intent.
Utterances can be aggregated for a bot alias or for a bot version, but not both at the same time.
Utterances statistics are not generated under the following conditions:
-
The
childDirected
field was set to true when the bot was created. -
You are using slot obfuscation with one or more slots.
-
You opted out of participating in improving Amazon Lex.
Request Syntax
POST /bots/botId
/aggregatedutterances/ HTTP/1.1
Content-type: application/json
{
"aggregationDuration": {
"relativeAggregationDuration": {
"timeDimension": "string
",
"timeValue": number
}
},
"botAliasId": "string
",
"botVersion": "string
",
"filters": [
{
"name": "string
",
"operator": "string
",
"values": [ "string
" ]
}
],
"localeId": "string
",
"maxResults": number
,
"nextToken": "string
",
"sortBy": {
"attribute": "string
",
"order": "string
"
}
}
URI Request Parameters
The request uses the following URI parameters.
- botId
-
The unique identifier of the bot associated with this request.
Length Constraints: Fixed length of 10.
Pattern:
^[0-9a-zA-Z]+$
Required: Yes
Request Body
The request accepts the following data in JSON format.
- aggregationDuration
-
The time window for aggregating the utterance information. You can specify a time between one hour and two weeks.
Type: UtteranceAggregationDuration object
Required: Yes
- botAliasId
-
The identifier of the bot alias associated with this request. If you specify the bot alias, you can't specify the bot version.
Type: String
Length Constraints: Fixed length of 10.
Pattern:
^(\bTSTALIASID\b|[0-9a-zA-Z]+)$
Required: No
- botVersion
-
The identifier of the bot version associated with this request. If you specify the bot version, you can't specify the bot alias.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 5.
Pattern:
^(DRAFT|[0-9]+)$
Required: No
- filters
-
Provides the specification of a filter used to limit the utterances in the response to only those that match the filter specification. You can only specify one filter and one string to filter on.
Type: Array of AggregatedUtterancesFilter objects
Array Members: Fixed number of 1 item.
Required: No
- localeId
-
The identifier of the language and locale where the utterances were collected. For more information, see Supported languages.
Type: String
Required: Yes
- maxResults
-
The maximum number of utterances to return in each page of results. If there are fewer results than the maximum page size, only the actual number of results are returned. If you don't specify the
maxResults
parameter, 1,000 results are returned.Type: Integer
Valid Range: Minimum value of 1. Maximum value of 1000.
Required: No
- nextToken
-
If the response from the
ListAggregatedUtterances
operation contains more results that specified in themaxResults
parameter, a token is returned in the response. Use that token in thenextToken
parameter to return the next page of results.Type: String
Required: No
- sortBy
-
Specifies sorting parameters for the list of utterances. You can sort by the hit count, the missed count, or the number of distinct sessions the utterance appeared in.
Type: AggregatedUtterancesSortBy object
Required: No
Response Syntax
HTTP/1.1 200
Content-type: application/json
{
"aggregatedUtterancesSummaries": [
{
"containsDataFromDeletedResources": boolean,
"hitCount": number,
"missedCount": number,
"utterance": "string",
"utteranceFirstRecordedInAggregationDuration": number,
"utteranceLastRecordedInAggregationDuration": number
}
],
"aggregationDuration": {
"relativeAggregationDuration": {
"timeDimension": "string",
"timeValue": number
}
},
"aggregationLastRefreshedDateTime": number,
"aggregationWindowEndTime": number,
"aggregationWindowStartTime": number,
"botAliasId": "string",
"botId": "string",
"botVersion": "string",
"localeId": "string",
"nextToken": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- aggregatedUtterancesSummaries
-
Summaries of the aggregated utterance data. Each response contains information about the number of times that the utterance was seen during the time period, whether it was detected or missed, and when it was seen during the time period.
Type: Array of AggregatedUtterancesSummary objects
- aggregationDuration
-
The time period used to aggregate the utterance data.
Type: UtteranceAggregationDuration object
- aggregationLastRefreshedDateTime
-
The last date and time that the aggregated data was collected. The time period depends on the length of the aggregation window.
-
Hours - for 1 hour time window, every half hour; otherwise every hour.
-
Days - every 6 hours
-
Weeks - for a one week time window, every 12 hours; otherwise, every day
Type: Timestamp
-
- aggregationWindowEndTime
-
The date and time that the aggregation window ends. Only data collected between the start time and the end time are returned in the results.
Type: Timestamp
- aggregationWindowStartTime
-
The date and time that the aggregation window begins. Only data collected after this time is returned in the results.
Type: Timestamp
- botAliasId
-
The identifier of the bot alias that contains the utterances. If you specified the bot version, the bot alias ID isn't returned.
Type: String
Length Constraints: Fixed length of 10.
Pattern:
^(\bTSTALIASID\b|[0-9a-zA-Z]+)$
- botId
-
The identifier of the bot that contains the utterances.
Type: String
Length Constraints: Fixed length of 10.
Pattern:
^[0-9a-zA-Z]+$
- botVersion
-
The identifier of the bot version that contains the utterances. If you specified the bot alias, the bot version isn't returned.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 5.
Pattern:
^(DRAFT|[0-9]+)$
- localeId
-
The identifier of the language and locale that the utterances are in.
Type: String
- nextToken
-
A token that indicates whether there are more results to return in a response to the
ListAggregatedUtterances
operation. If thenextToken
field is present, you send the contents as thenextToken
parameter of aListAggregatedUtterances
operation request to get the next page of results.Type: String
Errors
For information about the errors that are common to all actions, see Common Errors.
- InternalServerException
-
The service encountered an unexpected condition. Try your request again.
HTTP Status Code: 500
- PreconditionFailedException
-
Your request couldn't be completed because one or more request fields aren't valid. Check the fields in your request and try again.
HTTP Status Code: 412
- ThrottlingException
-
Your request rate is too high. Reduce the frequency of requests.
HTTP Status Code: 429
- ValidationException
-
One of the input parameters in your request isn't valid. Check the parameters and try your request again.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: