Define APIs for Alexa Conversations

---

When you configure a skill for Alexa Conversations, you must provide API definitions for all APIs that Alexa Conversations can call during the conversation between the user and Alexa. API definitions specify the requests that your skill code can handle.

As the user interacts with your skill, Alexa Conversations predicts the correct API based on the current dialog context. API definitions are analogous to intents in intent-based dialog models.

• Example
• API definitions, slot types, and responses
• API definitions and response acts
• API arguments
• Define an API
• Related topics

Example

Consider a weather skill that has a GetWeather API that accepts two arguments (date and city) and returns a returnedWeather value that contains properties for cityName, date, highTemperature, and lowTemperature. To use this API in an Alexa Conversations skill, you must create an API definition for the GetWeather API when you configure your skill in the developer console.

When you annotate dialogs for your skill, the API definitions are often what tie the user line and the Alexa line together. The following example shows what one dialog in your skill might be:

User: What's the weather in Seattle tomorrow?
Alexa: Tomorrow in Seattle, you can expect a high of 71 degrees and a low of 57 degrees.

When you annotate this dialog, you associate both the user utterance group and the Alexa response with the GetWeather API definition. The user utterance group provides the inputs to the API, and the Alexa response formats the output of the API into Alexa TTS.

API definitions, slot types, and responses

When you define an API, you specify an API name, input arguments, and a return type. Because APIs tie into slot types and responses, keep in mind that you also must do the following:

• Create slot types for any API arguments and return types that aren't built-in types. For details, see Use Slot Types.
  
  For example, if your weather skill returns the response, "Tomorrow in Seattle, you can expect a high of 71 degrees and a low of 57 degrees," you might create a returnedWeather slot type that contains a city, date, high temperature, and low temperature. For details about slot types, see Use Slot Types in Alexa Conversations.
• Create responses to define how Alexa responds to the user. For details, see Define Responses from Alexa for Alexa Conversations.

API definitions and response acts

Each API must have at least one dialog that uses the Request Args response act. You can't simply have a dialog where the user provides your arguments as part of the initial utterance.

API arguments

For higher API prediction accuracy, we recommend the following:

• Five or fewer arguments per API.
• Distinct types of arguments. For example, one argument of type AMAZON.NUMBER and another argument of type AMAZON.US_CITY typically performs better than two arguments that are both of type AMAZON.NUMBER.

Define an API

The following steps show how to define a simple API in the developer console. The steps include how to create a custom slot type for the API return type, which you must do before you create the API definition.

To create a custom slot type and an API definition

1. Log in to the developer console, and then navigate to your Alexa Conversations skill.
2. Create a custom slot type for the API return type by using the following steps:
   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 a name, and then click Next.
   4. For each property, click Add a new property, enter the property name, and then select the slot type.
   5. In the header bar, click Save.
3. Create the API definition by using the following steps:
   1. In the left pane, under Alexa Conversations, click API Definitions.
   2. Click Add API Definition.
   3. At the top, enter a name for the API.
   4. For each argument, click Add Argument, enter an argument name, and then select the slot type.
   5. Under Return, select custom slot type that you created.
   6. In the header bar, click Save.

For a full example, see Tutorial: Annotate a Dialog for Alexa Conversations.

Related topics

• Define Responses from Alexa for Alexa Conversations
• About Alexa Conversations
• Get Started with Alexa Conversations

---

---

Last updated: Nov 27, 2023