Tutorial: Offer an API in a Dialog with Alexa Conversations

---

In your Alexa Conversations skill, you can use the Offer Next API response act to have Alexa ask the user if they want to invoke another API. For example, in a weather skill, Alexa might ask the user, "Do you want to know the chance of rain?" after giving the user the temperature.

This tutorial walks you through how to add an Offer Next API turn to the dialog from Tutorial: Annotate a Dialog for Alexa Conversations. The dialog from that tutorial is as follows.

User: What's the weather?
Alexa: For what city?
User: Seattle.
Alexa: In Seattle, it's 70 degrees.

In this tutorial, you expand the dialog to offer the GetChanceOfRain API as follows.

User: What's the weather?

Alexa: For what city?
User: Seattle.

Alexa: In Seattle, it's 70 degrees.
Alexa: Do you want to know the chance of rain?
User: Yes.

Alexa: For what city?
User: Seattle.

Alexa: In Seattle, there's a 60 percent chance of rain.

• Steps to add an API offer to an Alexa Conversations skill
• Prerequisites
• Step 1: Add the dialog turns for the offer
• Step 2: Create custom slot types
• Step 3: Create an API definition
• Step 4: Configure the Alexa turn that offers an API
• Step 5: Configure the user turn that affirms the offer
• Step 6: Configure the Alexa turn that asks for the city
• Step 7: Configure the user turn that provides the city
• Step 8: Configure the Alexa turn that returns the result of the offered API
• Step 9: Build the skill model
• Related topics

Steps to add an API offer to an Alexa Conversations skill

Complete the following steps to add an Offer Next API turn to the skill:

1. Add the dialog turns for the offer.
2. Create custom slot types.
3. Create an API definition.
4. Configure the Alexa turn that offers an API.
5. Configure the user turn that affirms the offer.
6. Configure the Alexa turn that asks for the city.
7. Configure the user turn that provides the city.
8. Configure the Alexa turn that returns the result of the offered API.
9. Build the skill model.

Prerequisites

Before you do this tutorial, you must complete Tutorial: Annotate a Dialog for Alexa Conversations.

Step 1: Add the dialog turns for the offer

The first step is to add an Alexa turn that asks if the user wants to know the chance of rain. That is, Alexa asks the user if they want to invoke the GetChanceOfRain API. You then must continue the dialog until the user affirms that they want to call the API, and Alexa Conversations calls the API.

To add the dialog turns for the offer

1. In the developer console, navigate to the dialog you created in Tutorial: Annotate a Dialog for Alexa Conversations.
2. Under the dialog, click Alexa says, and then enter Do you want to know the chance of rain?
   Note: The dialog can't end with an Offer Next API turn. You must complete the dialog until the API Success turn of the offered API.
3. Click User says, and then enter Yes.
4. Click Alexa says, and then enter For what city?
   Note: Even though the user provided the city for the GetWeather API, Alexa Conversations requires a request for every mandatory API argument. In this case, the API is GetChanceOfRain.
5. Click User says, and then enter {city}.
6. Click Alexa says, and then enter In {city}, there's a {percentChanceOfRain} percent chance of rain.
7. In the header bar, click Save.

   

Step 2: Create custom slot types

For the new dialog turns, you must create the following two custom slot types:

• a type for the chance of rain, which contains a number.
• a type that you can specifically use to pass the result to the audio response of a successful call to the GetChanceOfRain API.

Create these types by using the following steps.

To create a custom slot type for the chance of rain

1. In the left pane, under Assets, click Slot Types.
2. Click Add Slot Type.
3. Select Create a custom slot type with properties, enter the name PercentChanceOfRainType, and then click Next.
4. Click Add a new property, enter the name city, and then select slot type AMAZON.US_CITY.
5. Repeat the previous step to add a property with the name percentChanceOfRain and slot type AMAZON.NUMBER.
6. In the header bar, click Save.

   

To create a custom slot type to pass the result to the audio response

1. In the left pane, under Assets, click Slot Types.
2. Click Add Slot Type.
3. Select Create a custom slot type with properties, enter the name PercentChanceOfRainTypeForSuccess, and then click Next.
4. Click Add a new property, enter the name returnedChanceOfRain, and then select slot type PercentChanceOfRainType.
5. In the header bar, click Save.

   

Step 3: Create an API definition

You must create an API definition for the new API. The API, which we call GetChanceOfRain, takes a city and returns the chance of rain.

To create an API definition

1. In the left pane, under Alexa Conversations, click API Definitions.
2. Click Add API Definition.
3. Replace the default name with the name GetChanceOfRain.
4. Under Arguments, click Add Argument.
5. For the argument name, enter city. For the slot type, select AMAZON.US_CITY.
6. Under Return, select the PercentChanceOfRainType slot type that you created.
7. In the header bar, click Save.

   

Step 4: Configure the Alexa turn that offers an API

Next, you configure the Alexa turn Do you want to know the chance of rain? with the Offer Next API response act.

To configure the dialog turn that offers an API

1. In the dialog, click anywhere within the Alexa turn Do you want to know the chance of rain?.
   An Alexa Response panel appears on the right.
2. For the response act, select Offer Next API.
3. For Next API to Offer, select GetChanceOfRain.
   API Arguments to Request automatically populates with city, and Alexa Conversations automatically creates a response called audioResponse1, which you edit next.
   Note: If this response doesn't contain Do you want to know the chance of rain? as a prompt, look through the other audioResponse* responses that Alexa automatically created, and select that one instead.
4. In the header bar, click Save.
5. In the left pane, under Audio Responses, click audioResponse1.
6. In the main window, rename the audio response to OfferChanceOfRain.
7. Under Alexa Prompts, click Add prompt, and then enter I can also tell you the chance of rain. Would you like to hear it?.
   Ignore the Type Configuration section. There are no variables in these Alexa prompts.
8. In the header bar, click Save.

   

9. Go back to your dialog, and click anywhere within the Alexa turn Do you want to know the chance of rain?.
10. In the Alexa Response panel, verify that that the selected Audio Response is OfferChanceOfRain.
11. In the header bar, click Save.

    

Step 5: Configure the user turn that affirms the offer

For the user turn, you define an utterance set of request act Affirm that groups together the variety of ways the user might say yes to the offer.

To configure the user turn that affirms the offer

1. In the dialog, click anywhere within the user turn Yes.
   A User Input panel appears on the right.
2. In the User Input panel, under Request Act, select Affirm.
3. Under Utterance Set, click the box and then select Create New Utterance Set.
   The utterance set configuration box appears.
4. Name the utterance set AffirmOffer.
   Because you already selected a request act, the request act box automatically populates with Affirm.
5. Under Sample Utterances, click Add Utterance, enter Ok, and then press enter.
6. Repeat the previous step and add sample utterance Yup, but don't press enter this time.
   Ignore the Type Configuration section. There are no variables in these utterances.
7. Click Save.
8. In the header bar, click Save.

   

Step 6: Configure the Alexa turn that asks for the city

You must configure the Alexa turn that requests the city to pass to the GetChanceOfRain API. Even though the user provided the city for the GetWeather API, Alexa Conversations requires a request for every mandatory API argument. In this case, the API is GetChanceOfRain.

To configure the Alexa turn that asks for the city

1. In the dialog, click anywhere within the unconfigured Alexa turn For what city?.
2. On the right, in the Alexa Response panel, under Response Act, select Request Args.
3. Under API to Request, click the box, and then select GetChanceOfRain.
   API Arguments to Request automatically populates with city.
4. Under Audio Response, select the RequestCity response.
5. In the header bar, click Save.

   

Step 7: Configure the user turn that provides the city

Next, you configure the user turn that provides the city in response to Alexa's request.

To configure the user turn that provides the city

1. In the dialog, click anywhere within the unconfigured user turn {city}.
2. On the right, in the User Input panel, for Request Act, select Inform Args.
3. For Utterance Set, select InformCity.
   Change Output Variable to city1.
4. In the header bar, click Save.

   

5. In the left panel, click Utterance Sets.
6. Delete any utteranceSet* utterance sets that Alexa Conversations might have created.
   There should only be four utterance sets: AffirmOffer, InformCity, InvokeGetWeather, and welcome. Failure to delete the others might break the model build.

Step 8: Configure the Alexa turn that returns the result of the offered API

Now you configure the final turn of the dialog, in which Alexa reports the chance of rain.

To configure the Alexa turn that returns the result of the offered API

1. In the dialog, click anywhere within the last Alexa turn, which corresponds to In {city}, there's a {percentChanceOfRain} percent chance of rain.
2. On the right, in the Alexa Response panel, for the response act, select API Success.
3. Under API to Invoke, click the box, and then select GetChanceOfRain.
   A Variables → Arguments mapping appears under GetChanceOfRain.
4. Configure the variable-to-argument mapping to the following:
   city1.city → city
   Return Type → Variable automatically populates with PercentChanceOfRainType → percentChanceOfRainType0.
5. In the header bar, click Save.
   Alexa Conversations automatically creates a response called audioResponse2, which you edit next.
6. In the header bar, click Save.
7. In the left pane, under Audio Responses, click audioResponse2.
8. In the main window, rename the audio response to ReturnChanceOfRain.
9. Under Type Configuration, select the PercentChanceOfRainTypeForSuccess slot type that you created.
10. Scroll back up to the Alexa Prompts section, and double-click {city}.
11. From the drop-down menu, select returnedChanceOfRain.city.
12. Double-click {percentChanceOfRain}.
13. From the drop-down menu, select returnedChanceOfRain.percentChanceOfRain.
14. Under Properties, if a percentChanceOfRain property appeared, delete this property.
    The only property should be returnedChanceOfRain.
15. In the header bar, click Save.

    

16. Back in the dialog, click anywhere within the last Alexa turn, which corresponds to In {city}, there's a {percentChanceOfRain} percent chance of rain.
17. On the right, in the Alexa Response panel, scroll to the bottom and expand Properties of PercentChanceOfRainTypeForSuccess.
18. Configure the variable mapping to the following:
    percentChanceOfRainType0 → returnedChanceOfRain

    

19. In the header bar, click Save.

    

Step 9: Build the skill model

Your next step is to build the skill model.

To build the skill model

• In the header bar, click Build Model.
  The light Alexa Conversations build begins. If the build fails, click back through all of the lines of your dialog, and ensure that you don't see any red errors. Also, see Issue: I get errors when I build the model.

If the light build succeeds, the full build begins.

Related topics

• Troubleshoot Your Alexa Conversations Skill
• Tutorial: Annotate a Dialog
• Get Started with Alexa Conversations

---

---

Last updated: Nov 27, 2023