Clear the Context in the Alexa Conversations Description Language

Note: Sign in to the developer console to build or publish your skill.

Note: Alexa Conversations Description Language (ACDL) is offered as a beta and may change as we receive feedback and iterate on the feature.

To provide a natural conversational experience, Alexa Conversations maintains the conversational context within a skill session. For example, in a pizza skill, if the user selects all their pizza toppings and then later changes the size of their pizza, Alexa Conversations retains all the previously chosen pizza toppings.

API argument values are part of the conversational context. By default, Alexa Conversations carries over all arguments between API calls. If you don't want to carry over arguments, you can specify which arguments to reset. You indicate which arguments to reset by applying a policy to your skill.

Policy overview
Policy types
- ResetArguments policy
- ResetAllArguments policy
  - Example: Reset all arguments
Unsupported use cases
Related topics

Policy overview

To reset arguments, you use one of the following two Policy types in your Alexa Conversations Description Language (ACDL):

ResetArguments – This policy resets the specified arguments of an API after that API is invoked. In other words, when the API is invoked again, Alexa Conversations doesn't use the argument values from the previous API call. However, other APIs can still use the argument values.
ResetAllArguments – This policy resets all arguments (across all APIs) after Alexa Conversations invokes a specific API.

To use a policy, you declare the policy and then include the policy in the policies argument of the skill() action. The following example shows how to declare and include policies.

getWeatherResetArgumentsPolicy = ResetArguments{arguments = 
                [getWeather.arguments.cityName, getWeather.arguments.day]}

getWeatherResetAllArgPolicy = ResetAllArguments{action = GetWeather}

mySkill = skill(
   locales = [...],
   skillLevelResponses = {...},
   policies = [getWeatherResetArgumentsPolicy, getWeatherResetAllArgPolicy]
)

Note: The default behavior is for arguments to carry over. In other words, arguments aren't reset unless you use policies.

For details and examples, see ResetArguments and ResetAllArguments.

Policy types

The following section describes the ResetArguments and ResetAllArguments policy types.

ResetArguments policy

To prevent carryover of an argument between subsequent calls to the same API, you use the ResetArguments policy. When you declare a policy based on the ResetArguments type, you provide a list of arguments to reset after the associated API is called.

To declare a ResetArguments policy, use the following syntax.

MyPolicyName = ResetArguments{
   arguments=
   [ MyAPIName.arguments.arg1,
     MyAPIName.arguments.arg2, 
     MyAPIName.arguments.arg3,
     ...
   ]
}

You can use the ResetArguments policy on optional arguments. As with required arguments, optional arguments are carried over by default, unless you set a policy that specifies otherwise. The inclusion of an optional argument in a policy doesn't affect whether Alexa Conversations should or shouldn't request the argument. However, if Alexa Conversations determines that the argument needs to be requested, Alexa Conversations applies the policy.

For examples of how to use ResetArguments, see the following sections:

Reset each argument of an API
Reset some, but not all, arguments of an API
Reset the attributes of an API return value
Reset an optional argument

Example: Reset each argument of an API

The following example shows what happens when the skill uses a ResetArguments policy to reset each argument of the AddCustomPizzaApi API. When the user invokes AddCustomPizzaApi a second time, Alexa Conversations asks the user for the size, cheese, crust, and toppings again.

action AddCustomPizzaResult AddCustomPizzaApi(
size, crust, toppings, cheese)

resetPolicy = ResetArguments{
arguments=
[AddCustomPizzaApi.arguments.size,
AddCustomPizzaApi.arguments.crust,
AddCustomPizzaApi.arguments.toppings,
AddCustomPizzaApi.arguments.cheese]}

mySkill = skill(
  locales = [...],
  skillLevelResponses = {...},
  policies = [resetPolicy]
)

Speaker	Speech or Action
User	"Order a pizza."
Alexa	"Okay, what size?"
User	"Small."
Alexa	"What toppings do you want on your pizza?"
User	"Mushrooms, pepperoni, and jalapenos."
Alexa	"On what kind of crust? We have traditional, deep-dish, and thin crust."
User	"Deep-dish."
Alexa	"How do you like the cheese? You can ask for no cheese, light, normal, extra, or double cheese."
User	"Light cheese."
N/A	Alexa Conversations calls `AddCustomPizzaApi(cheese="Light cheese", crust="Deep-dish", size="Small", toppings=["Mushrooms", "Pepperoni", "Jalapenos"])`.

At this point, Alexa Conversations resets the arguments associated with the AddCustomPizzaApi API. Continuing the conversation, when the user orders another pizza, they need to specify the size and toppings from scratch.

Speaker	Speech or Action
User	"Order another pizza."
Alexa	"Okay, what size?"
User	"Medium."
Alexa	"What toppings do you want on your pizza?"
User	"Green peppers and olives."
Alexa	"On what kind of crust? We have traditional, deep-dish, and thin crust."
User	"Thin."
Alexa	"How do you like the cheese? You can ask for no cheese, light, normal, extra, or double cheese."
User	"Extra cheese."
N/A	Alexa Conversations calls `AddCustomPizzaApi(cheese="Extra cheese", crust="Thin", size="Medium", toppings=["Green peppers", "Olives"])`.

Example: Reset some, but not all, arguments of an API

In the following example, the policy specifies that the day argument of a GetWeather API should be reset across subsequent calls to GetWeather. Because the city argument isn't included in the policy, the city argument is carried over.

action WeatherResult GetWeather(US_CITY cityName, DATE day)

resetPolicy = ResetArguments{arguments=[GetWeather.arguments.day]}

mySkill = skill(
  locales = [...],
  skillLevelResponses = {...},
  policies = [resetPolicy]
)

Speaker	Speech or Action
User	"What's the weather in Seattle on Sunday?"
N/A	Alexa Conversations calls `GetWeather(city="Seattle", day="Sunday")`.
Alexa	"In Seattle, on Sunday, it will be 70 degrees."

At this point, Alexa Conversations resets only the day argument. If the user continues the conversation and asks for the weather a second time, Alexa asks for the day again, but not the city.

Speaker	Speech or Action
User	"What's the weather?"
Alexa	"What day?"
User	"Wednesday."
N/A	Alexa Conversations calls `GetWeather(city="Seattle", day="Wednesday")`.
Alexa	"In Seattle, on Wednesday, it will be 65 degrees."

Example: Reset the attributes of an API return value

The following example shows how you can reset the attributes of the API return value for the associated API, yet other APIs can still use the collected values.

action WeatherResult GetWeather(US_CITY cityName, DATE day)
action AverageWeatherResult GetAverageWeather(US_CITY cityName, DATE day)

resetPolicy = ResetArguments{arguments=[GetWeather.arguments.cityName, GetWeather.arguments.day]}

mySkill = skill(
  locales = [...],
  skillLevelResponses = {...},
  policies = [resetPolicy]
)

Speaker	Speech or Action
User	"What's the weather in Seattle on Sunday?"
N/A	Alexa Conversations calls `GetWeather(city="Seattle", day="Sunday")` and returns `WeatherResult`.
Alexa	"In Seattle, on Sunday, it will be 70 degrees."

At this point, Alexa Conversations resets the city and day argument for GetWeather. The next time the user invokes GetWeather, Alexa will ask the user for the city and day again. However, if the user invokes a different API, such as GetAverageWeather, the arguments are reused.

Speaker	Speech or Action
User	"What's the average weather?"
N/A	Alexa Conversations calls `GetAverageWeather(city="Seattle", day="Sunday")`.
Alexa	"In Seattle, the yearly average for this Sunday is 68 degrees."

The GetWeather API, on the other hand, can't use the previously collected city and day argument values, because those values were cleared.

Speaker	Speech or Action
User	"What's the weather?"
Alexa	"What city?"
User	"Nashville."
Alexa	"What day?"
User	"Friday."
N/A	Alexa Conversations calls `GetWeather(city="Nashville", day="Friday")`.
Alexa	"In Nashville, on Friday, it will be 80 degrees."

Example: Reset an optional argument

The following example shows how you can reset an optional argument.

action Result FindRecipe( optional Cuisine cuisine, 
                                     optional Difficulty difficulty)

resetPolicy = ResetArguments{arguments=[FindRecipe.arguments.cuisine, 
                                FindRecipe.arguments.difficulty]}

mySkill = skill(
  locales = [...],
  skillLevelResponses = {...},
  policies = [resetPolicy]
)

Speaker	Speech or Action
User	"Find me an Indian recipe."
N/A	Alexa Conversations calls `FindRecipe(cuisine="Indian")`.

At this point, Alexa Conversations resets the cuisine argument, so Alexa Conversations doesn't have a cuisine in context anymore.

Speaker	Speech or Action
User	"Find me an easy recipe."
N/A	Alexa Conversations calls `FindRecipe(difficulty="easy")`.
Alexa	"I found an easy recipe for Thai food. Would you like to try it?"

ResetAllArguments policy

You use the ResetAllArguments policy to prevent the carryover of all arguments (across all APIs) after Alexa Conversations invokes a particular API. In other words, this policy deletes everything from the context, such as elicited arguments and API returns.

API MyAPI (
  arg1, 
  arg2,
  arg3
)
resetPolicy = ResetAllArguments(MyAPI)

mySkill = skill(
  locales = [...],
  skillLevelResponses = {...},
  policies = [resetPolicy]
)

Example: Reset all arguments

The following example has both a GetWeather API and a GetCurrentWeather API. The ACDL specifies that the context should be reset after GetWeather is called, but not after GetCurrentWeather is called.

API GetWeather (
  city,
  day
)
API GetCurrentWeather (
  city
)
resetPolicy = ResetAllArguments(GetWeather)

mySkill = skill(
  locales = [...],
  skillLevelResponses = {...},
  policies = [resetPolicy]
)

Speaker	Speech or Action
User	"What's the weather in Seattle on Sunday?"
N/A	Alexa Conversations calls `GetWeather(city="Seattle", day="Sunday")`.
Alexa	"In Seattle, on Sunday, it will be 70 degrees."

At this point, Alexa Conversations resets all arguments across all APIs. Continuing the conversation, the user asks for the current weather, which invokes the GetCurrentWeather API. Because all arguments were reset after the call to GetWeather, Alexa must ask for the city again.

Speaker	Speech or Action
User	"What's the current weather?"
Alexa	"What city?"
User	"Nashville."
N/A	Alexa Conversations calls `GetCurrentWeather(city="Nashville")`.
Alexa	"In Nashville, it's 85 degrees."

Continuing the conversation, the user asks for the weather, which invokes the GetWeather API. Because no arguments were reset after the call to GetCurrentWeather, Alexa only needs to ask for the day again.

Speaker	Speech or Action
User	"What's the weather?"
Alexa	"What day?"
User	"Friday."
N/A	Alexa Conversations calls `GetWeather(city="Nashville", day="Friday")`.
Alexa	"In Nashville, on Friday, it will be 68 degrees."

Unsupported use cases

At this time, Alexa Conversations doesn't support the following use cases:

Conditionally resetting arguments for the same API. An example of this unsupported behavior is resetting arguments based on a user utterance.
Using ResetArguments to reset arguments that other APIs use. However, you can clear the entire context by using ResetAllArguments.
Using ResetAllArguments to reset arguments for two APIs that share the same argument type.

Was this page helpful?

Provide feedback

Last updated: Nov 27, 2023