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 dialog 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 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.

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

You define APIs to your skill in the developer console as follows.

To create an API definition

1. Log in to the developer console, and then navigate to your Alexa Conversations skill.
2. In the left pane, click API Definitions.
3. Click Add API Definition.
4. Enter a name for the API.

5. 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.)
   1. Under Arguments, click Add Argument.
   2. Enter the argument name and select a slot type.
   3. Click Add Argument to add other arguments, if applicable.
6. Under Return, select the slot type of the return value.
   For details about slot types, see Use Slot Types in Alexa Conversations.
7. In the header bar, click Save.

Related topics

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

---

---

Last updated: Nov 27, 2023