Collect Multiple Values in a Slot

Use a multiple-value slot to collect multiple values from a user utterance into single slot. For example, an utterance like "Plan a trip to go hiking, camping, and fishing" sends your skill an array with three values in a single {activity} slot. This lets the user provide multiple values in a more natural utterance.

You can use multiple-value slots in the following locales:

  • English (AU)

  • English (CA)

  • English (UK)

  • English (US)

About multiple value slots

Multiple-value slots let users provide a list of items in a more natural way. Instead of stringing together multiple slots or asking multiple questions to get a list of related items, you can use a single slot. In your interaction model, you define your sample utterances with a single slot that collects all the values:

Plan a trip to go {activity}

When a user speaks this utterance, they can say multiple items separated with pauses, the conjunction "and", or a combination of the two. For example:

User: Plan a trip to go hiking, camping, and fishing

Your skill gets a request with an array of values as the slot value for the activity slot. In the trip planning example, the array contains three items (full details removed for brevity):

{
  "values": [
    {
      "type": "Simple",
      "value": "hiking",
      "resolutions": {}
    },
    {
      "type": "Simple",
      "value": "camping",
      "resolutions": {}
    },
    {
      "type": "Simple",
      "value": "fishing",
      "resolutions": {}
    }
  ]
}

Valid user utterances for a multiple value slot

A multiple-value slot requires the user to separate values in the utterance with pauses, "and", or a combination of the two. For example, the following utterances are valid ways to fill a multiple value activity slot:

  • "Plan a trip to go camping"
  • "Plan a trip to go camping and hiking."
  • "Plan a trip for camping, hiking."
  • "Plan a trip to go camping, hiking, and fishing."
  • "Plan a trip with camping, hiking, fishing, horseback riding."

Steps to use a multiple-value slot in your skill

Using a multiple value slot requires you to update your interaction model and change your skill code to accommodate changes in the IntentRequest.

To create a multiple-value slot

  1. Create your interaction model with at least one custom intent with at least one slot.
  2. Configure the slot for multiple values as described in Configure a slot to accept multiple values.
  3. Update your skill code to handle the revised slot object in the IntentRequest. For details, see Update your code to handle the multiple-value slot object and IntentRequest slot object reference.
  4. Test the utterances you expect users to speak. Test many different combinations of list items and verify that your skill gets the correct set of values. Update the slot type with more values as needed to improve recognition. See Test the slot and revise your model as needed.

Configure a slot to accept multiple values

You configure a slot to collect multiple values on the intent, not on the slot type. A multiple-value slot can use any custom or built-in slot type except for AMAZON.SearchQuery.

When you write your utterances, reference the slot as you normally would, with curly braces:

plan a trip to go {activity}
i want to go {activity}
plan a trip from {fromCity} to {toCity} to go {activity}
i'm going to {toCity} to go {activity}
...

You can configure the multiple value option in the developer console or with the ASK CLI.

Use the developer console to configure a slot for multiple values

  1. Open your skill in the developer console.
  2. Click an intent in the left-hand navigation to open the detail page for the intent.
  3. In the list of Intent Slots, find the slot to change. The MULTI-VALUE column indicates whether this slot can collect multiple values.
  4. Click the slot to open the slot detail page.
  5. Under Multi-Value, enable the Can this slot contain multiple values? option.
Multiple value setting for a slot
Multiple value setting for a slot

Use the ASK CLI to configure a slot for multiple values

  1. In the JSON file for your interaction model, update the intent slot you want to configure. Set interactionModel.languageModel.intents[].slots[].multipleValues.enabled to true.

     {
       "name": "PlanMyTripIntent",
       "slots": [
         {
           "name": "toCity",
           "type": "AMAZON.City"
         },
         {
           "name": "travelDate",
           "type": "AMAZON.DATE"
         },
         {
           "name": "fromCity",
           "type": "AMAZON.City"
         },
         {
           "name": "activity",
           "type": "ListOfActivities",
           "multipleValues": {
             "enabled": true
           }
         }
       ],
       "samples": [
         "i want to go {activity}",
         "plan a trip from {fromCity} to {toCity} to go {activity}",
         "i'm going to {toCity} to go {activity}",
         "i want to do {activity}",
         "plan a trip to go {activity}",
         "plan a trip to {toCity} to go {activity}"
       ]
     }
    

    For a reference to the interaction model JSON, see Interaction model schema reference.

  2. Use the ASK CLI deploy command to upload and deploy the interaction model.

     ask deploy --profile "default" --target "model"
    

Interaction model schema reference

Multiple-value slots change the schema for defining a slot. The multipleValues object lets you enable multiple values for the slot:

{
  "name": "IntentName",
  "slots": [
    {
      "name": "slotName",
      "type": "slotType",
      "multipleValues": {
        "enabled": true
      }
    }
  ],
  "samples": []
}
Property Description Type Required

multipleValues

Determines whether this slot allows single values or multiple values. When this object is not present, the slot defaults to allowing single values only.

Object

No

multipleValues.enabled

When true, the slot recognizes and collects multiple values spoken in list format, such as "pepperoni, mushrooms, and black olives".

Boolean

No

For more about the interaction model JSON structure, see Interaction Model Schemas.

Update your code to handle the multiple-value Slot object

The structure of the Slot object in the IntentRequest has changed for all requests and all slots, even those that you don't configure for multiple values. These changes are fully backwards-compatible. Your existing code that accesses values for single-value slots continues to work unchanged. However, you must update your code to access a slot that returns multiple-values.

The following sections describe the overall changes. For the full reference to the updated Slot object, see IntentRequest Slot object reference.

The slotValue property and the legacy value and resolutions properties

When the user provides a slot value in an utterance, the corresponding Slot object in the IntentRequest includes a new slotValue property. Access this at request.intent.slots.slotName.slotValue:

{
  "slotName": {
    "name": "slotName",
    "value": "user-provided slot value",
    "resolutions": {},
    "slotValue": {
      "type": "Simple",
      "value": "user-provided slot value",
      "resolutions": {}
    },
    "confirmationStatus": "NONE",
    "source": "USER"
  }
}

The slotValue property contains a SlotValue object that represents the value the user provided. The SlotValue object represents either a single value or list of values. The slotValue.type property is Simple for single values or List for multiple values.

The slotValue property is present regardless of how you configured the slot in your interaction model. That is, a slot configured for single values also includes the slotValue property when the user provides a value. When the slot is left unfilled, slotValue is omitted.

When the user speaks a single value for the slot, the Slot object reports the value in two places, regardless of the slot configuration:

  • The new slotValue property in slotValue.value and slotValue.resolutions
  • The legacy value and resolutions properties at the top level of the Slot object.

For example, if you configured the activity slot for multiple values, but the user filled the slot with the single value "hiking" that value is available in both places:

{
  "activity": {
    "name": "activity",
    "value": "hiking",
    "resolutions": {},
    "confirmationStatus": "NONE",
    "source": "USER",
    "slotValue": {
      "type": "Simple",
      "value": "hiking",
      "resolutions": {}
    }
  }
}

When the user provides multiple values for the slot, the array of values is available in the slotValue.values array. The slot doesn't include the legacy value and resolutions properties. Existing code that expects those properties doesn't work.

{
  "activity": {
    "name": "activity",
    "slotValue": {
      "type": "List",
      "values": [
        {
          "type": "Simple",
          "value": "hiking",
          "resolutions": {}
        },
        {
          "type": "Simple",
          "value": "camping",
          "resolutions": {}
        }
      ]
    },
    "confirmationStatus": "NONE",
    "source": "USER"
  }
}

Note that each object within the slotValue.values array is also a SlotValue object and therefore has the type, value and resolutions properties.

Because of this structure, you might want to change your code for accessing slot values to use the new slotValue property for all requests, not just those with multiple values. Use the slotValue.type property to distinguish between requests with single and multiple values.

Entity resolution

Entity resolution resolves the spoken value into a slot value and provides additional information for the slot values, such as unique identifiers and multiple possible matches. Entity resolution also resolves spoken synonyms to your slot values.

Entity resolution generates values for both single-value and multiple-value slots. The new slotValue property includes entity resolution results for each value:

  • For a single-value slot, or a multiple-value slot where the user spoke a single value, entity resolution results are in the slotValue.resolutions property. The same results are also in the legacy resolutions property.
  • For a multiple-value slot, resolutions for each value are in the resolutions property for each individual value in the values array: slotValue.values[].resolutions.

This example shows a slot with a single value. The resolutions data is available in both the legacy resolutions property and slotValue.resolutions. The results include two potential ER matches for the utterance "biking".

{
  "activity": {
    "name": "activity",
    "value": "biking",
    "resolutions": {
      "resolutionsPerAuthority": [
        {
          "authority": "amzn1.er-authority.echo-sdk.amzn1.ask.skill.1.ListOfActivities",
          "status": {
            "code": "ER_SUCCESS_MATCH"
          },
          "values": [
            {
              "value": {
                "name": "bicycling",
                "id": "BIKE"
              }
            },
            {
              "value": {
                "name": "mountain biking",
                "id": "MTN_BIKE"
              }
            }
          ]
        }
      ]
    },
    "confirmationStatus": "NONE",
    "source": "USER",
    "slotValue": {
      "type": "Simple",
      "value": "biking",
      "resolutions": {
        "resolutionsPerAuthority": [
          {
            "authority": "amzn1.er-authority.echo-sdk.amzn1.ask.skill.1-e271-4a72-a8c8-e27853cdc8d1.ListOfActivities",
            "status": {
              "code": "ER_SUCCESS_MATCH"
            },
            "values": [
              {
                "value": {
                  "name": "bicycling",
                  "id": "BIKE"
                }
              },
              {
                "value": {
                  "name": "mountain biking",
                  "id": "MTN_BIKE"
                }
              }
            ]
          }
        ]
      }
    }
  }
}

This example shows multiple values for the same slot when the user said "biking, rock climbing, and boating". Each value has its own entity resolution results. In this example, there are again two possible matches for the utterance "biking". In addition, the value "boating" is not defined in the custom slot type, as shown by the ER_SUCCESS_NO_MATCH code.

{
  "activity": {
    "name": "activity",
    "confirmationStatus": "NONE",
    "source": "USER",
    "slotValue": {
      "type": "List",
      "values": [
        {
          "type": "Simple",
          "value": "biking",
          "resolutions": {
            "resolutionsPerAuthority": [
              {
                "authority": "amzn1.er-authority.echo-sdk.amzn1.ask.skill.1.ListOfActivities",
                "status": {
                  "code": "ER_SUCCESS_MATCH"
                },
                "values": [
                  {
                    "value": {
                      "name": "bicycling",
                      "id": "BIKE"
                    }
                  },
                  {
                    "value": {
                      "name": "mountain biking",
                      "id": "MTN_BIKE"
                    }
                  }
                ]
              }
            ]
          }
        },
        {
          "type": "Simple",
          "value": "rock climbing",
          "resolutions": {
            "resolutionsPerAuthority": [
              {
                "authority": "amzn1.er-authority.echo-sdk.amzn1.ask.skill.1.ListOfActivities",
                "status": {
                  "code": "ER_SUCCESS_MATCH"
                },
                "values": [
                  {
                    "value": {
                      "name": "rock climbing",
                      "id": "ROCK_CLIMB"
                    }
                  }
                ]
              }
            ]
          }
        },
        {
          "type": "Simple",
          "value": "boating",
          "resolutions": {
            "resolutionsPerAuthority": [
              {
                "authority": "amzn1.er-authority.echo-sdk.amzn1.ask.skill.1.ListOfActivities",
                "status": {
                  "code": "ER_SUCCESS_NO_MATCH"
                }
              }
            ]
          }
        }
      ]
    }
  }
}

For more details about entity resolution, see Entity Resolution.

When testing your skill, consider adding values that resolve to ER_SUCCESS_NO_MATCH to your custom slot type to improve multiple-value recognition. For more details, see Test the slot and revise your model as needed.

The __Conjunction slot

When an IntentRequest includes a slot configured for multiple values, the request sent to your skill includes an additional slot called __Conjunction. This contains the conjunction the user spoke to separate the values. The only supported conjunction is "and".

IntentRequest slot object reference

This section shows the complete structure for the Slot object included in an IntentRequest. For the full IntentRequest format, see IntentRequest.

Slot object

Syntax

{
  "slotName": {
    "name": "slotName",
    "value": "String representing the user-provided value",
    "resolutions": {},
    "slotValue": {},
    "confirmationStatus": "NONE | CONFIRMED | DENIED",
    "source": "USER"
  }
}

Properties

Name Description Type

confirmationStatus

An enumeration indicating whether the user has explicitly confirmed or denied the value of this slot. Possible values: NONE, CONFIRMED, DENIED

Enum

name

A string that represents the name of the slot.

String

resolutions

Included when the user provided a single value for the slot (slotValue.type is Simple). A Resolutions object representing the results of resolving the words captured from the user's utterance.

Included for slots that use a custom slot type or a built-in slot type that you have extended with your own values. Omitted when slotValue.type is List.

This property is provided for backwards-compatibility and provides the resolutions for a single slot value. Use the slotValue property to retrieve resolutions for either single or multiple values.

Resolutions object

slotValue

A SlotValue object representing the value or values captured by the slot.

SlotValue object

source

Indicates that the value came from the user. Always USER.

String

value

Included when the user provided a single value for the slot (slotValue.type is Simple). A string that represents the value the user spoke for the slot. This string is the actual value the user spoke, not necessarily the canonical value or one of the synonyms defined for the entity. Omitted when slotValue.type is List.

This property is provided for backwards-compatibility and can only contain a single slot value. Use the slotValue property to retrieve either single or multiple values.

String

Resolutions object

Syntax

{
  "resolutions": {
    "resolutionsPerAuthority": [
      {
        "authority": "Identifier for the authority",
        "status": {
          "code": "Enum indicating ER status "
        },
        "values": [
          {
            "value": {
              "name": "String representing the resolved value",
              "id": "Identifier for the value"
            }
          }
        ]
      }
    ]
  }
}

Properties

Name Description Type

resolutionsPerAuthority[]

An array of objects representing each possible authority for entity resolution. An authority represents the source for the data provided for the slot. For a custom slot type, the authority is the slot type you defined.

Array

resolutionsPerAuthority[].authority

The name of the authority for the slot values. For custom slot types, this authority label incorporates your skill ID and the slot type name.

String

resolutionsPerAuthority[].status

An object representing the status of entity resolution for the slot.

Object

resolutionsPerAuthority[].status.code

A code indicating the results of attempting to resolve the user utterance against the defined slot types. See Entity resolution status codes.

Enum

resolutionsPerAuthority[].values

An array of resolved values for the slot. The values in the array are ordered from the most likely to least likely matches. Therefore, the first value in the array is considered the best match.

Array

resolutionsPerAuthority[].values[].value

An object representing the resolved value for the slot, based on the user's utterance and the slot type definition.

Object

resolutionsPerAuthority[].values[].value.id

The unique ID defined for the resolved slot value. This is based on the IDs defined in the slot type definition. For details about defining slot values and IDs, see Create Synonyms and Unique Identifiers for Custom Slot Type Values.

String

resolutionsPerAuthority[].values[].value.name

The string for the resolved slot value.

String

SlotValue object

Syntax

A SlotValue object contains either value or values, but never both.

{
  "slotValue": {
    "type": "Type of value (Simple or List)",
    "value": "When type is Simple, string representing the user-provided value.",
    "values": [
      {
        "type": "",
        "value": "",
        "resolutions": {}
      }
    ],
    "resolutions": {}
  }
}

Properties

Name Description Type

resolutions

Included when the type is Simple. A Resolutions object representing the results of resolving the words captured from the user's utterance.

Included for slots that use a custom slot type or a built-in slot type that you have extended with your own values.

Resolutions object

type

The type of value the slot captured from the user. Simple when the slot value is a single value , List when the slot value is an array of values.

String

value

Included when type is Simple. A string that represents the value the user spoke for the slot. This string is the actual value the user spoke, not necessarily the canonical value or one of the synonyms defined for the entity.

This value is the same as the the Slot object value property.

String

values

Included when thetype is List. An array of SlotValue objects representing the set of values the user provided. Each object in the array has its own type, value, and resolutions.

Array of SlotValue objects

Entity resolution status codes

  • ER_SUCCESS_MATCH – The spoken value matched a value or synonym explicitly defined in your custom slot type.
  • ER_SUCCESS_NO_MATCH – The spoken value didn't match any values or synonyms explicitly defined in your custom slot type.
  • ER_ERROR_TIMEOUT – An error occurred due to a timeout.
  • ER_ERROR_EXCEPTION – An error occurred due to an exception during processing.

Test the slot and revise your model as needed

Test your skill with a variety of utterances in your multiple-value slots. Test both filling those slots with single values and lists of values. Keep in mind that recognition for multiple slot values works best when the utterance contains five or fewer values.

To test a multiple-value slot, use any of the following:

Update your model to improve accuracy as you test. For custom slot types and built-in list types, Alexa is more accurate at parsing utterances into the correct multiple values when the slot type includes those values. When you discover values that Alexa fails to recognize correctly, do one of the following:

  • Custom slot typesEdit the slot and add the values you expect users to say to the slot type.
  • Built-in list typesExtend the slot type with those additional values.

Multiple-value list management

If you use the ASK SDK Controls Framework (Beta) in your skill, you can use MultiValueListControl to manage the items a user adds to and removes from their list. MultiValueListControl handles item validation and interactions to confirm and prompt to make it easy to integrate multiple-value slots into your skill. The control supports voice and multimodal presentation by using Alexa Presentation Language (APL) on an Alexa-enabled device with a screen. For examples, see Multiple-value list control examples.

MultiValueListControl object details

For details about the MultiValueListControl definition, see ASK SDK Controls Framework (Beta).

.
Property Description Type
id A unique identifier for this instance of the control. string
slotType The slot type of the multiple-value list. This value can be a custom slot type or a built-in list slot type from your custom interaction model. string
listItemIDs An array of the value IDs from which the user can choose. This list is typically a subset of the slot value IDs defined in slotType. An array of slot value IDs or a function that returns an array of slot value IDs
validation (Optional) Function to determine if the user input is valid. If you define a validation function, it must return either true or a MultiValueValidationFailure to describe the validation failure.
The default is true, any given value is valid.
A function with or without arguments
confirmationRequired (Optional) Function that determines if Alexa should confirm the user's selection, with a yes/no question. Is true, if Alexa should confirm the items before adding them to the list and removing them from the list.
The default is false, no confirmation required.
boolean or function
prompts (Optional) Dialog that Alexa says under certain conditions. A MultiValueListControlPromptProps object
reprompts (Optional) Dialog that Alexa says when re-prompting the user for input. A MultiValueListControlPromptProps object
interactionModel (Optional) Properties to customize the relationship between the control and the custom interaction model. A MultiValueListControlInteractionModelProps object
inputHandling (Optional) Properties to define input handling for this control. A ControlInputHandlingProps object
apl (Optional) Function that determines if the control should generate APL output on Alexa-enabled devices. You can also customize APL properties, such as swipe action.
The default is false, APL isn't required.
A MultiValueListControlAPLProps object

Prompt configuration

The MultiValueListControlPromptProps object contains a set of prompts that you can configure Alexa to say under certain conditions, such as when a validation fails, to confirm a response, or to request input. For each prompt, configure a text string or a function that returns a text string for Alexa to speak. All prompts are optional and have default values for English.

Prompt Description
invalidValue What Alexa says after the user makes an invalid selection to add items to the list.
invalidRemoveValue What Alexa says after the user makes an invalid selection to remove items from the list.
requestValue What Alexa says to request the user to make a selection to add to the list.
requestRemovedValue What Alexa says to request the user to make a selection to remove from the list.
confirmValue What Alexa says to confirm the selection, as a yes/no question.
valueConfirmed What Alexa says after the user confirms the items.
valueAdded What Alexa says to confirm the item that the user wants to add to the list.
valueRemoved What Alexa says to confirm the item that the user wants to remove from the list.
valueCleared What Alexa says to confirm that the user wants to clear the list.
suggestAction What Alexa says to suggest available actions, like add an item to the list, remove an item from the list, and clear the list.

Multiple-value list control examples

The following example shows a default interaction using MultiValueListControl with required properties.

Alexa: What is your selection?
User: I want to go camping and swimming.
Alexa: Swimming isn't a valid value. You can say biking, camping, ….

Copied to clipboard.

    const activityControl = new MultiValueListControl({
      id: 'myActivityList',
      slotType: 'ListOfActivities',
      listItemIDs:['biking', 'camping', 'hiking', 'mountain biking']
    });

The following example shows an interaction using MultiValueListControl configured with confirmation enabled and three custom prompts.

Alexa: What would you like to do on your trip?
User: I want to go hiking and biking.
Alexa: Added hiking and biking. Is that all?
User: Yes, that's it.
Alexa: OK, great!

Copied to clipboard.

    const activityControl = new MultiValueListControl({
      id: 'myActivityList',
      slotType: 'ListOfActivities',
      listItemIDs:['biking', 'camping', 'hiking', 'mountain biking'],
      confirmationRequired: ()=> true,
      prompts: {
        requestValue: () => "What would you like to do on your trip?",
        confirmValue: () => "Is that all?",
        valueConfirmed: "OK, great!"
      }
    });

Best practices to improve slot accuracy

Use the following tips to improve the recognition of your slot values:

  • Use multiple-value slots with custom slot types and the built-in list slot types. Although you can use the slot types for numbers, dates, and times, such as the AMAZON.Date slot, the accuracy is better with list slot types.
  • A multiple-value slot works best with a custom slot type that has a very complete catalog of possible values.
  • When you create your list of slot values, be sure to include the most likely or frequent entries. This is especially important if you create a large catalog of values and encounter limits on your interaction model size. Prioritize the most likely values.
  • For slot values with multiple words, be sure to include those phrases as values in the slot type. For example, include values such as "chocolate milk" in a GroceryList slot type. Test utterances that use these multi-word values to ensure that they recognize correctly.
  • Address ambiguities by adding additional values to your slot type. When the utterance is ambiguous and can be interpreted in multiple ways, Alexa prioritizes the longest slot value.

    For example, the utterance "add sour cream and onion chips to my list" could be interpreted in multiple ways, depending on the slot type values.

    • When the slot type catalog contains the value "sour cream and onion chips", Alexa interprets the utterance as a single value ("sour cream and onion chips").
    • When the slot type catalog contains "sour cream" and "onion chips" as separate values, Alexa interprets the utterance as separate values ("sour cream", "onion chips").
    • When the slot type catalog contains all three ("sour cream and onion chips", "sour cream", "onion chips"), Alexa chooses the longest slot value and therefore interprets the utterance as a single value "sour cream and onion chips". In this case, users can still get the separate values by changing the way they word the utterance. For example, "add onion chips and sour cream" would return the two separate values ("sour cream", "onion chips").
  • When you use a multiple-value slot with dynamic entities, avoid including entities that could cause ambiguities in your dynamic catalog. For example, don't include all three values "peanut", "butter" and "peanut butter" in your dynamic catalog. The machine learning models used for dynamic entities work differently, so ambiguous entities might give you less accurate results.
  • Recognition is better when the user's utterance contains five or fewer items. Avoid slot design that requires the user to provide a longer list of items.

Limitations for multi-value slots

  • You can't use a dialog model for an intent that has a multiple value slot. This means:
    • You can't use auto-delegation to collect the slot values.
    • You can't use the Dialog.Delegate, Dialog.ElicitSlot, or Dialog.ConfirmSlot directives.
  • When you publish your skill, you provide up to three example phases to show users how to interact with your skill. You can use a phrase that illustrates providing multiple values in your set of example phrases. However, note that the developer console might display a warning that the phrase does not match your sample utterances. You can ignore this warning and submit the skill.