Handle API Calls for Alexa Conversations
• GA:
en-US
, en-AU
, en-CA
, en-IN
, en-GB
, de-DE
, ja-JP
, es-ES
, es-US
• Beta:
it-IT
, fr-CA
, fr-FR
, pt-BR
, es-MX
, ar-SA
, hi-IN
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.
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 ofDialog.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.
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.
Related topics
Last updated: Nov 27, 2023