Request Types Reference (LaunchRequest, CanFulfillIntentRequest, IntentRequest, SessionEndedRequest)

The Alexa service sends your service a request using one of the standard request types when users engage with your skill by voice. There are several request types:

  • LaunchRequest: Sent when the user invokes your skill without providing a specific intent.
  • IntentRequest: Sent when the user makes a request that corresponds to one of the intents defined in your intent schema.
  • SessionEndedRequest: Sent when the current skill session ends for any reason other than your code closing the session.
  • CanFulfillIntentRequest: Sent when the Alexa service is querying a skill to determine whether the skill can understand and fulfill the intent request with detected slots, before actually asking the skill to take action.

If you implement the AudioPlayer, PlaybackController, or GameEngine interface, your skill receives additional requests beyond the standard request types. See AudioPlayer Interface, PlaybackController Interface, and GameEngine Interface for details.

For the overall request format, see JSON Interface Reference for Custom Skills - Request Format.

LaunchRequest

A LaunchRequest is an object that represents that a user made a request to an Alexa skill, but did not provide a specific intent.

{
  "type": "LaunchRequest",
  "requestId": "string",
  "timestamp": "string",
  "locale": "string"
}

LaunchRequest Parameters

Parameter Description Type
type Describes the request type with the value as: "LaunchRequest" string
timestamp Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to verify the request when hosting your skill as a web service. string
requestId Represents a unique identifier for the specific request. string
locale A string indicating the user's locale. For example: en-US. See supported locale codes. string

Valid Response Types

Your service can respond to LaunchRequest with any combination of:

If you include both standard properties and an AudioPlayer directive, Alexa processes the standard properties first. For example, if you provide outputSpeech in the same response as an Play directive, Alexa speaks the provided text before beginning to stream the audio.

CanFulfillIntentRequest

A CanFulfillIntentRequest is an object that represents a request made to skill to query whether the skill can understand and fulfill the intent request with detected slots, before actually asking the skill to take action. For information about the request format, see Understand Name-free Interaction for Custom Skills.

Response to CanFulfillIntentRequest

Your service can respond to CanFulfillIntentRequest with canFulfillIntent. See Understand Name-free Interaction for Custom Skills.

See Response Body Syntax for the general response parameters. In addition, the following parameters are unique to canFulfillIntent.

canFulfillIntent Parameters

Parameter Description Type Required

canFulfill (for intent)

Represents an overall response to whether the skill can understand and fulfill the intent with detected slots. The following are possible values:

  • YES - Your skill understands all slots, can fulfill all slots, and can handle the request in its entirety.

  • NO - Your skill either cannot understand the intent, cannot understand all the slots, or cannot fulfill all the slots.

  • MAYBE - Your skill can understand the intent, can partially or fully understand the slots, and can partially or completely fulfill the slots. Only respond with MAYBE when the skill partially understands the request and can potentially complete the request if the skill gets more data through callbacks or through a multi-turn conversation with the user.

When making ranking decisions, Alexa tracks the skill's response to CanFulfillIntentRequest and may use it in conjunction with customer feedback on whether the skill actually fulfilled customer requests. Thus, the response of YES, NO, or MAYBE is not the only factor influencing the decision to use the skill to respond to a customer request.

enum

Yes

slots

A map that represents a detailed response to each detected slot within the intent and whether the skill can understand and fulfill the slot. The map supplements the overall canFulfill response for the intent, and helps Alexa make better ranking and arbitration decisions. The name of the slot is the key, and the value is an object of type slots. For each slot, canUnderstand has possible values of YES, NO, or MAYBE, and canFulfill has possible values of YES or NO.

object

Yes

IntentRequest

An IntentRequest is an object that represents a request made to a skill based on what the user wants to do.

{
  "type": "IntentRequest",
  "requestId": "string",
  "timestamp": "string",
  "dialogState": "string",
  "locale": "string",
  "intent": {
    "name": "string",
    "confirmationStatus": "string",
    "slots": {
      "SlotName": {
        "name": "string",
        "value": "string",
        "confirmationStatus": "string",
        "resolutions": {
          "resolutionsPerAuthority": [
            {
              "authority": "string",
              "status": {
                "code": "string"
              },
              "values": [
                {
                  "value": {
                    "name": "string",
                    "id": "string"
                  }
                }
              ]
            }
          ]
        }
      }
    }
  }
}

IntentRequest Parameters

Parameter Description Type
type Describes the type of the request with the value as: "IntentRequest". string
requestId Represents the unique identifier for the specific request. string
timestamp Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to verify the request when hosting your skill as a web service. string
dialogState Enumeration indicating the status of the multi-turn dialog. This property is included if the skill meets the requirements to use the Dialog directives Possible values: STARTED, IN_PROGRESS, COMPLETED.

Note that COMPLETED is only possible when you use the Dialog.Delegate directive.

If you use intent confirmation, dialogState is considered COMPLETED if the user denies the entire intent (for instance, by answering "no" when asked the confirmation prompt). Be sure to also check the confirmationStatus property on the Intent object before fulfilling the user's request.
string
intent An object that represents what the user wants. For the definition of the intent object, see Intent Object. object
locale A string indicating the user's locale. For example: en-US. See supported locale codes. string

Intent Object

Parameter Description Type

name

A string representing the name of the intent.

string

confirmationStatus

An enumeration indicating whether the user has explicitly confirmed or denied the entire intent. Possible values:

  • NONE
  • CONFIRMED
  • DENIED

slots

A map of key-value pairs that further describes what the user meant based on a predefined intent schema. The map can be empty.

  • The key is a string that describes the name of the slot. Type: string.
  • The value is an object of type slot. Type: object. See Slot Object.

map

For more about how you define the intents your skill can handle, see:

Slot Object

Parameter Description Type

name

A string that represents the name of the slot.

string

value

A string that represents the value the user spoke for the slot. This is the actual value the user spoke, not necessarily the canonical value or one of the synonyms defined for the entity.

Note that AMAZON.LITERAL slot values sent to your service are always in all lower case.

string

confirmationStatus

An enumeration indicating whether the user has explicitly confirmed or denied the value of this slot. Possible values:

  • NONE
  • CONFIRMED
  • DENIED

string

resolutions

A Resolutions object representing the results of resolving the words captured from the user's utterance.

This is included for slots that use a custom slot type or a built-in slot type that you have extended with your own values. Note that resolutions is not included for built-in slot types that you have not extended. See Entity Resolution for Built-in Slot Types.

object

Resolutions Object

See Define Synonyms and IDs for Slot Type Values (Entity Resolution) for details about defining custom slot types with synonyms and ID values for entity resolution.

Parameter Description Type

resolutionsPerAuthority[]

An array of objects representing each possible authority for entity resolution. An authority represents the source for the data provided for the slot. For a custom slot type, the authority is the slot type you defined.

array

resolutionsPerAuthority[].authority

The name of the authority for the slot values. For custom slot types, this authority label incorporates your skill ID and the slot type name.

string

resolutionsPerAuthority[].status

An object representing the status of entity resolution for the slot.

object

resolutionsPerAuthority[].status.code

A code indicating the results of attempting to resolve the user utterance against the defined slot types. This can be one of the following:

  • ER_SUCCESS_MATCH: The spoken value matched a value or synonym explicitly defined in your custom slot type.
  • ER_SUCCESS_NO_MATCH: The spoken value did not match any values or synonyms explicitly defined in your custom slot type.
  • ER_ERROR_TIMEOUT: An error occurred due to a timeout.
  • ER_ERROR_EXCEPTION: An error occurred due to an exception during processing.

string

resolutionsPerAuthority[].values

An array of resolved values for the slot.

array

resolutionsPerAuthority[].values[].value

An object representing the resolved value for the slot, based on the user's utterance and the slot type definition.

object

resolutionsPerAuthority[].values[].value.name

The string for the resolved slot value.

string

resolutionsPerAuthority[].values[].value.id

The unique ID defined for the resolved slot value. This is based on the IDs defined in the slot type definition.

string

Valid Response Types

Your service can respond to IntentRequest with any combination of:

If you include both standard properties and an AudioPlayer directive, Alexa processes the standard properties first. For example, if you provide outputSpeech in the same response as an Play directive, Alexa speaks the provided text before beginning to stream the audio.

SessionEndedRequest

A SessionEndedRequest is an object that represents a request made to an Alexa skill to notify that a session was ended. Your service receives a SessionEndedRequest when a currently open session is closed for one of the following reasons:

  1. The user says "exit".
  2. The user does not respond or says something that does not match an intent defined in your voice interface while the device is listening for the user's response.
  3. An error occurs.
{
  "type": "SessionEndedRequest",
  "requestId": "string",
  "timestamp": "string",
  "reason": "string",
  "locale": "string",
  "error": {
    "type": "string",
    "message": "string"
  }
}

SessionEndedRequest Parameters

Parameter Description Type

type

Describes the type of the request with the value as: "SessionEndedRequest"

string

requestId

Represents the unique identifier for the specific request.

string

timestamp

Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to verify the request when hosting your skill as a web service.

string

reason

Describes why the session ended. Possible values:

  • USER_INITIATED: The user explicitly ended the session.
  • ERROR: An error occurred that caused the session to end.
  • EXCEEDED_MAX_REPROMPTS: The user either did not respond or responded with an utterance that did not match any of the intents defined in your voice interface.

string

locale

A string indicating the user's locale. For example: en-US. See supported locale codes.

string

error

An error object providing more information about the error that occurred. This object includes the properties:

  • type: a string indicating the type of error that occurred (INVALID_RESPONSE, DEVICE_COMMUNICATION_ERROR, INTERNAL_ERROR).
  • message: a string providing more information about the error.

object

Valid Response Types

Your skill cannot return a response to SessionEndedRequest.

Request Examples

LaunchRequest Example

{
  "version": "1.0",
  "session": {
    "new": true,
    "sessionId": "amzn1.echo-api.session.0000000-0000-0000-0000-00000000000",
    "application": {
      "applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
    },
    "attributes": {},
    "user": {
      "userId": "amzn1.account.AM3B00000000000000000000000"
    }
  },
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
      },
      "user": {
        "userId": "amzn1.account.AM3B00000000000000000000000"
      },
      "device": {
        "supportedInterfaces": {
          "AudioPlayer": {}
        }
      }
    },
    "AudioPlayer": {
      "offsetInMilliseconds": 0,
      "playerActivity": "IDLE"
    }
  },
  "request": {
    "type": "LaunchRequest",
    "requestId": "amzn1.echo-api.request.0000000-0000-0000-0000-00000000000",
    "timestamp": "2015-05-13T12:34:56Z",
    "locale": "string"
  }
}

IntentRequest Example

{
  "version": "1.0",
  "session": {
    "new": false,
    "sessionId": "amzn1.echo-api.session.0000000-0000-0000-0000-00000000000",
    "application": {
      "applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
    },
    "attributes": {
      "supportedHoroscopePeriods": {
        "daily": true,
        "weekly": false,
        "monthly": false
      }
    },
    "user": {
      "userId": "amzn1.account.AM3B00000000000000000000000"
    }
  },
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
      },
      "user": {
        "userId": "amzn1.account.AM3B00000000000000000000000"
      },
      "device": {
        "supportedInterfaces": {
          "AudioPlayer": {}
        }
      }
    },
    "AudioPlayer": {
      "offsetInMilliseconds": 0,
      "playerActivity": "IDLE"
    }
  },
  "request": {
    "type": "IntentRequest",
    "requestId": " amzn1.echo-api.request.0000000-0000-0000-0000-00000000000",
    "timestamp": "2015-05-13T12:34:56Z",
    "dialogState": "COMPLETED",
    "locale": "string",
    "intent": {
      "name": "GetZodiacHoroscopeIntent",
      "confirmationStatus": "NONE"
      "slots": {
        "ZodiacSign": {
          "name": "ZodiacSign",
          "value": "virgo",
          "confirmationStatus": "NONE"
        }
      }
    }
  }
}

SessionEndedRequest Example

{
  "version": "1.0",
  "session": {
    "new": false,
    "sessionId": "amzn1.echo-api.session.0000000-0000-0000-0000-00000000000",
    "application": {
      "applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
    },
    "attributes": {
      "supportedHoroscopePeriods": {
        "daily": true,
        "weekly": false,
        "monthly": false
      }
    },
    "user": {
      "userId": "amzn1.account.AM3B00000000000000000000000"
    }
  },
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
      },
      "user": {
        "userId": "amzn1.account.AM3B00000000000000000000000"
      },
      "device": {
        "supportedInterfaces": {
          "AudioPlayer": {}
        }
      }
    },
    "AudioPlayer": {
      "offsetInMilliseconds": 0,
      "playerActivity": "IDLE"
    }
  },
  "request": {
    "type": "SessionEndedRequest",
    "requestId": "amzn1.echo-api.request.0000000-0000-0000-0000-00000000000",
    "timestamp": "2015-05-13T12:34:56Z",
    "reason": "USER_INITIATED",
    "locale": "string"
  }
}

Service Interface Reference (JSON)

Request Format and Standard Request Types:

Interfaces: