Handle API Calls for Alexa Conversations

To invoke an API in your skill, Alexa sends your skill a request of type Dialog.API.Invoked. The fields of the request contain the name of the API and values for arguments and slots. Your skill must be able to handle all APIs that you defined in Define APIs for Alexa Conversations.

The requests and responses that Alexa uses to communicate with your skill are similar to the format described in the Request and Response JSON Reference for custom skills, with a few differences. For a summary of the differences, see Request and Response Reference for Alexa Conversations.

Tip

To see examples of how to handle requests and send responses in an Alexa Conversations skill, consider using an Alexa-hosted sample skill template. You can use the online code editor in the developer console to examine the skill code. For instructions on how to create a skill based on a template, see Get Started With Alexa Conversations.

Receiving requests

Suppose your Alexa Conversations skill defines a GetWeather API that has two input arguments, date and cityName. After Alexa collects a date and a cityName from the user during the course of the conversation, Alexa sends your skill a request of type Dialog.API.Invoked such as the following.

{
  "type": "Dialog.API.Invoked",
  "requestId": "amzn1.echo-api.request.edbb146d-a38a-4e31-9010-eab4403981b7",
  "timestamp": "2020-01-02T02:35:15Z",
  "locale": "en_US",
  "apiRequest": {
    "name": "GetWeather",
    "arguments": {
      "date": "2020-01-01",
      "cityName": "seattle"
    },
    "slots": {
      "date": {
        "type": "Simple",
        "value": "2020-01-01"
      },
      "cityName": {
        "type": "Simple",
        "value": "seattle",
        "resolutions": {..} // Optional, for entity resolution
      }
    }
  }
}

Returning responses

When you send a response to a Dialog.API.Invoked request, you must return one, and only one, of the following in the response object:

  • An apiResponse object to indicate that the Alexa Conversations model should keep predicting actions in the dialog.
  • A Dialog.DelegateRequest directive to transfer dialog management control to the skill. For examples of Dialog.DelegateRequest directives, see Hand off Dialog Management to and from Alexa Conversations.

You must not return both an apiResponse object and a Dialog.DelegateRequest directive. For the full set of rules, see Response handling.

The schema for a response with an apiResponse object is as follows.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "apiResponse": {
      "cityName": "seattle",
      "lowTemperature": 50,
      "highTemperature": 65
    }
  }
}

The content of the apiResponse must match the returned type in the API definition that you configured in Define APIs for Alexa Conversations. These objects can be multi-level JSON objects.

The skill code that handles the GetWeather API by using the Node.JS SDK looks similar to the following.

Copied to clipboard.

const GetWeatherApiHandler = {
    canHandle(handlerInput) {
        return util.isApiRequest(handlerInput, 'GetWeatherApi');
    },
    handle(handlerInput) {
        const cityNameWithId = util.getCityNameWithIdFromApiRequestSlots(handlerInput);

        if (!cityNameWithId) {
            // We couldn't match this city value to our slot, so we'll return 
            // empty and let the response template handle it.
            return {apiResponse:{}};
        }

        // Call a service to get the weather for this location and date.
        const weather = weatherClient.getWeather(cityNameWithId.id);

        const response = {
            apiResponse: {
                cityName: cityNameWithId.name,
                lowTemperature: weather.lowTemperature,
                highTemperature: weather.highTemperature
            }
        }

        return response;
    }
}

Ending the skill session

To indicate that you want to end the skill session, return a response with shouldEndSession set to true in response to a Dialog.API.Invoked request. By doing so, you enable the API Success (or API Failure) response to render and then end the session and close the microphone.

Was this page helpful?

Last updated: Nov 27, 2023