Collect Multiple Values in a Slot

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

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.

5. Update the slot type with more values as needed to improve recognition. For details, 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.

To configure a slot for multiple values with the developer console

1. Open the Alexa developer console, and then sign in.
2. On the Skills tab, in the SKILL NAME column, click the name of your custom skill.
3. From the left-hand sidebar, click Custom > Interaction Model > Intents.
4. Click an intent to open the detail page for the intent.

5. In the list of Intent Slots, find the slot to change.

   The MULTI-VALUE column shows whether this slot can collect multiple values.

6. Click the slot to open the slot detail page.
7. Under Multi-Value, select the Can this slot contain multiple values? option.

To configure a slot for multiple values with the ASK CLI

1. In the JSON file for your interaction model, find the intent to configure.

2. Set interactionModel.languageModel.intents[].slots[].multipleValues.enabled to true.

   The following example configures the activity slot for the PlanMyTripIntent to allow multiple values.

    {
      "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.

3. To upload and deploy the interaction model, use the ASK CLI deploy command.

    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 slots.

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

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

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 property 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 user leaves the slot 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"
  }
}

Entity resolution

Entity resolution (ER) 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.

The following 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"
                }
              }
            ]
          }
        ]
      }
    }
  }
}

The following 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" isn't 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 you test 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 slot contains the conjunction the user spoke to separate the values. The only supported conjunction is "and".

IntentRequest slot object reference

The following 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 that represents the user-provided value",
    "resolutions": {},
    "slotValue": {},
    "confirmationStatus": "NONE | CONFIRMED | DENIED",
    "source": "USER"
  }
}

Properties

Resolutions object

Syntax

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

Properties

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 that represents the user-provided value.",
    "values": [
      {
        "type": "",
        "value": "",
        "resolutions": {}
      }
    ],
    "resolutions": {}
  }
}

Properties

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 tools:

• A device. For details, see Test and Debug Your Skill.

• The Alexa simulator on the Test page in the developer console. For details, see Test with the Alexa Simulator.

  When you type utterances in the Test page, separate the slot values with either spaces, or spaces and commas. For example, either of these utterances would work:

  "hiking camping and fishing"

  "hiking, camping, and fishing"

• The utterance profiler. For details, see Test Your Utterances as You Build Your Model.

  When you type utterances into the utterance profiler, separate the slot values with spaces. For example, "hiking camping and fishing".

• The NLU evaluation tool. For details, see Batch Test Your Natural Language Understanding (NLU) Model.

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, perform one of the following actions:

• Custom slot types – Edit the slot and add the values you expect users to say to the slot type.
• Built-in list types – Extend 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).

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.

Multiple-value list control examples

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

    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.

    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 Alexa recognizes them correctly.

• Address ambiguities by adding additional values to your slot type. When the utterance is ambiguous and Alexa can interpret it in multiple ways, Alexa prioritizes the longest slot value.

  For example, Alexa could interpret the utterance "add sour cream and onion chips to my list" 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 phrases to show users how to interact with your skill. You can use a phrase that illustrates how to provide multiple values in your set of example phrases. However, be aware that the developer console might display a warning that the phrase doesn't match your sample utterances. You can ignore this warning and submit the skill.

Related topics

• Create the Interaction Model for Your Skill
• Create Intents, Utterances, and Slots
• Test Skills in the Alexa Developer Console

Last updated: Aug 08, 2024