Alexa Skills Kit    >    Get Deeper    >    Tutorials & Code Samples    >   Build Multi-turn Skills Tutorial with Alexa Conversations

We're Still in Beta...

Alexa Conversations is still in beta and updates may have been released that are not reflected in this tutorial yet. If you have questions or feedback about Alexa for Conversations, Click on the feedback button on the lower right-hand corner.

Module 5: Keep track of the conversation with context carry-over  

Welcome to module 5 Keep track of the conversation with context carry-over. Context carry-over is something we all do without thinking. For example, let’s say our customer asks for a largelow-energy family dog and we recommend a Great Pyrenees. After some consideration our customer decides that a Great Pyrenees is too big and asks, "How about a medium-sized dog?". With context carry over, our skill doesn’t need to re-prompt for the energy and temperament slots. Instead Alexa Conversations will replace the value of large with medium, send a new JSON request to the skill code and recommend an American Eskimo.

What You'll Learn:

  • How to set up a simple skill called Pet Match with step-by-step instructions

  • How to use the Alexa Developer Console

  • How to host your skill’s backend resources

  • How to modify the response that Alexa speaks to customers

Time Required: 50 minutes

line-break

Alexa Conversations Vs. Dialog Management  

Dialog Management 

When building an Alexa skill with Dialog Management, once the dialogState is COMPLETED, the previously collected information is no longer included in the request sent to our skill code. Let’s recall our earlier example where our customer requests a change to one of our search parameters after our skill has returned a recommendation. At this point our skill code has stopped returning dialog delegates so the dialogState is COMPLETED.

Upon asking for a "medium-sized dog" the skill will start from a fresh state, so all the previously collected values are empty. In order to support context carry-over, you have to store that information somewhere.

A common approach is to store the slots in the session attributes and check the dialogState at run-time with your skill code. The steps to achieve this method assuming your intent managed with Dialog Management is called RecommendationIntent are:

  • Store the previously collected search parameters (slots) in session attributes

  • Requested intent equals RecommendationIntent and dialogState is STARTED:

    1. Check the session attributes for previously collected values

      1. If none exist this the first time our customer is making a selection

        1. return a dialog delegate

      2. If any of the parameters are different make a new query

        1. return the new recommendation

That’s quite a lot of steps that we have to manage at run-time. If we wanted to clear the search and start over, we’d also need to add an intent and a set of utterances to enable our customers to do so.

Alexa Conversations

On the other hand Alexa Conversations tracks the state of the conversation on your behalf. Your skill code receives the API request once Alexa Conversations has determined that it has all the required information necessary to call your API. If your customer changes their mind, you’ll get context carry-over for free!

If you want to have the skill acknowledge the change of parameters and say something like, "after changing from a large to a medium-sized dog, I would recommend an American Eskimo". You can update your dialog with a new turn, define a new variable to contain the new value, and update the response template.

Now that you have an understanding of what you’re going to do, it’s time to start building!

line-break

Step 1: Update the Dialog

We’ll start by updating dialog0 with the following lines:

U: How about a medium sized dog?

A: Ok, after changing large to medium, I recommend an American Eskimo.

We’ll start by updating dialog0 with the following lines:

U: I want a large family dog.

A: Do you prefer high energy or low energy dogs?

U: high energy

A: So you want a large high energy family dog. I recommend a Labrador.

U: How about a medium sized dog?

A: In that case I recommend an American Eskimo.

a. Click on Dialogs
 

b. Edit dialog0
 

c. Click on the User says button.

User Says

d. In the textbox that says, "What might a user say," enter How about a medium dog.

Since you’re not collecting any new slots, you can reuse the build-time assets you previously created.
 

e. Double-click on medium.

A modal will appear allowing you to select a slot type.
 

f. Select size from the drop-down.

The user interface will auto-populate the variable name textbox with size1. Leave this as is. This will allow you reference the old and new size slot values in your response template.
 

g. Click Add

image

Now you need to choose your utterance set and configure the mapping.
 

h. From the User Input panel, select Invoke APIs.

i. select invoke_getRecommendation_size from the Utterance Set drop-down.

Tip 

After clicking either the User or Alexa says button, the UI automatically moves your cursor into the input field. Once you’ve finished entering the text, click on the input field to make the User Input or Alexa Response panel appear.

j. Select size1 from the Slot → Variable drop-down.

image

You’ve finished the user input! Now you need to define Alexa’s response.
 

k. Click the Alexa says button.

alexa says

l. Into the text field enter, Ok, after changing large to medium, I recommend an American Eskimo.
 

m. From the Alexa Response panel, select API Success from the Dialog Act drop-down.
 

n. Next to API to Invoke(Required), click the + button.
 

o. From the drop-down select getRecommendation.

The sizetemperament, and energy arguments and the recommendationResult return variable will auto populate, so all you need to do is select the argument variables from the drop-down. Since you added a new size1 variable, you’ll set the size argument to size1 and leave the rest to 0.
 

p. Select size1 from the size drop-down.
 

q. select temperament0 from the temperament drop-down.
 

r. Select energy0 from the energy drop-down.

User Says
Note

The Return Type → Variable will automatically be populated with getRecommendationResult0. If you wanted to keep track of both matches, you set the variable to getRecommendationResult1.

By doing this you are telling Alexa Conversations to pass the new size value to the getRecommendation API and keep the old one. This will allow you to keep both matches in context. You could reuse notifySuccess_getRecommendation and Pet Match would return a valid response. In order to provide context though you’ll create a new response template that uses size0 and size1.
 

s. From the Response drop-down select Create New Response.

The Edit Response modal will appear.
 

t. In the Response Name field enter notifySuccess_getRecommendation_context_carry_over.

Note

Although the next item on the form is the Audio response, let’s create our Arguments first. You’ll create three, two size parameters oldSizenewSize and recommendationResult.

u. Scroll down to Arguments.
 

v. Click Add Argument.
 

w. Enter Type Name oldSize as the NAME of the new argument.
 

x. Select size from the Slot Type drop-down.
 

Repeat the steps above for the two remaining arguments, newSize and recommendationResult. Use the table below for reference.

Name Slot Type
newSize size
recommendationResult getRecommendationResult

image

Now that you’ve defined your arguments, it’s time to define the Audio Response.

line-break

Step 2: Define the Audio Response

APIs can support multiple response templates. At run-time, Alexa Conversations will determine which one to use based upon your dialog. Once you’ve updated the prompt, your skill will be able to say something like, "Okay, so if you want a small dog instead of a large dog, I’d recommend an American Eskimo."

We’ll start by adding an APLA document notify_api_GetRecommendation_context_carry_over.
 

a. Scroll up to Audio Response (required).

image

b. From the drop-down, select Create a new prompt

A grey box with input boxes allowing you to define the Audio Response Name and Alexa Prompts.
 

c. In the Audio Response Name field, enter prompt_notifySuccess_getRecommendation_context_carry_over.
 

d. Click the grey Save button.

image
Tip 

You want to be sure to click the grey save button which saves the prompt, not the blue save button which saves the Response and closes the modal. If you did click the blue save button click the pencil icon next to the Response drop-down.

Replace Values with Slots

You should have one Alexa Prompt that says:

Ok, after changing large to medium, I recommend an American Eskimo

You will now turn this prompt into a template and replace the hard-coded values, largemedium and American Eskimo with their corresponding slot.
 

e. Double-click large.

The Select Slot Type modal will appear.
 

f. Click oldSize.
 

g. Double-click medium.
 

h. Click newSize.
 

i. Highlight American Eskimo.
 

j. Select name which appears under the recommendationResult.

image

Now that you’ve finished mapping the values to slots, take a look at the prompt.

Ok, after changing {oldSize} to {newSize}, I recommend an {recommendationResult.name}

As you can see, it replaced large with {oldSize}, medium with {newSize} and American Eskimo with {recommendationResult.name}. At run-time these placeholders will be replaced with their actual values.
 

k. Click the grey Save button.

save

l. Click the blue Save button.

save

The Edit Response modal will disappear and your newly created notifySuccess_getRecommendation_context_carry_over response templated will automatically be selected in the response drop-down.

All that’s left to do is map that variables to the arguments.
 

m. Locate the Variable → Arguments section under the response drop-down.
 

n. Select size0 from the top drop-down to map it to oldSize.
 

o. Select size1 from the middle drop-down to map it to newSize.
 

p. Select getRecommendationResult1 from the bottom drop-down to map it to recommendationResult.

image

Now all you need to do is associate your new template with the getRecommendation API definition. You can do that one of two ways. You can either click on API Definitions in the left navigation menu and select getRecommendation or you can do it in-line right here from the dialog edit page. Let’s do it in-line so we don’t have to jump from page to page.
 

q. From the Alexa Response panel, locate API to Invoke(Required) and click the pencil next to the drop-down that has getRecommendation selected.

image

The Edit API Definition modal will appear.
 

r. Scroll down to the section that says Responses and select notifySuccess_getRecommendation_context_carry_over from the drop-down.
 

s. Click on the + button to add the response template to the getRecommendation API. Congratulations you now have an API that has multiple response templates associated to it. At run-time, Alexa Conversations will be able to figure out which one to use.

image

t. Click Save.

save

At this point you’re ready to save and build your model!
 

u. Click the save button with the floppy disk icon on it.

save

v. Click Build.

save

Since you didn’t make any changes to your API definitions or the data that your skill code sends back, you don’t need to update any of your code! Alexa Conversations is doing the heavy lifting for you at run-time. Before you can test you’ll need to wait until your model finishes building. Once that process completes, move to step 3 to test your skill!

line-break

Step 3 Test

Navigate to the test tab and open the skill. Ask Pet Match for a large low energy family dog. Does the skill recommend a Great Pyrenees? If so, great! Now type, "How about a medium dog?" If the skill recommends an American Eskimo you’ve just harnessed the power of Alexa Conversations to handle a context carry-over simply by reconfiguring your dialog.

line-break

Wrap Up

With a minimal amount of effort, you were able to update your dialog and add a new response template to the getRecommendation API defintion in order to provide context when the customer changes their mind.

line-break

Code

If your skill isn’t working or you’re getting some kind of syntax error, download the code sample in Node.js from the link below. Then, go to the Code tab in the Alexa developer console and copy and paste the code into the index.js file. Be sure to save and deploy the code before testing it.
 

Node.js Github Code Sample