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.
To get started with Alexa Conversations, you can step through a pet match skill-building tutorial, download the code for a pizza-ordering reference skill, or use an Alexa-hosted sample skill template that includes an Alexa Conversations skill configuration and back-end skill code.
- API definitions, slot types, and responses
- API definitions and dialog acts
- API arguments
- Define an API
- Related topics
Consider a weather skill that has a
GetWeather API that accepts two arguments (
city) and returns a
returnedWeather value that contains properties for
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
returnedWeatherslot 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 dialog acts
Each API must have at least one dialog that uses the Request Args dialog act. You can't simply have a dialog where the user provides your arguments as part of the initial utterance.
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.NUMBERand another argument of type
AMAZON.US_CITYtypically performs better than two arguments that are both of type
Define an API
You define APIs to your skill in the developer console as follows.
To create an API definition
- Log in to the developer console, and then navigate to your Alexa Conversations skill.
- In the left pane, click API Definitions.
- Click Add API Definition.
- Enter a name for the API.
If the API has arguments, do the following:Note: Alexa Conversations currently doesn't support APIs that take multiple list arguments. (Each API can have at most one list argument.)
- Under Arguments, click Add Argument.
- Enter the argument name and select a slot type.
- Click Add Argument to add other arguments, if applicable.
- Under Return, select the slot type of the return value.
For details about slot types, see Use Slot Types in Alexa Conversations.
- In the header bar, click Save.