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 additional interfaces, such as AudioPlayer or PlaybackController, your skill receives additional requests beyond the standard request types. See the documentation for the interface for details on the requests that interface can send to your skill. For a list of custom skill interfaces, see Interfaces.

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:

  • Standard response properties (outputSpeech, card, and reprompt).

  • Any AudioPlayer directive.

    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.

  • Any Dialog directive. You must specify an intent in the updatedIntent parameter of the directive. This lets you immediately start a dialog with the user.

    You can include OutputSpeech in your response along with the Dialog directive. For Dialog.Delegate, Alexa speaks the outputSpeech before the prompts defined in the dialog model. For the other Dialog directives, the speech is used as the prompt to ask for slot values or confirmation.

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",
        "slotValue": {},
        "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 has a dialog model. Possible values:

  • STARTED—User invoked the intent that has a dialog.
  • IN_PROGRESS—Dialog is in progress.
  • COMPLETED—Dialog is complete. All required slots contain values, and all values meet any defined slot validation rules. This state is possible only when you delegate the dialog to Alexa.

If the dialog model defines intent confirmation rules, the dialogState is COMPLETED regardless of whether the user confirmed or denied the entire intent (for instance, by answering "no" when asked the confirmation prompt). 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

Name Description Type

confirmationStatus

An enumeration that shows whether the user has explicitly confirmed or denied the value of this slot. Possible values: NONE, CONFIRMED, DENIED

Enum

name

A string that represents the name of the slot.

String

resolutions

Included when the user provided a single value for the slot (slotValue.type is Simple). A Resolutions object that represents the results of resolving the words captured from the user's utterance.

Included for slots that use a custom slot type or a built-in slot type that you have extended with your own values. Omitted when slotValue.type is List.

This property is provided for backwards-compatibility and provides the resolutions for a single slot value. Use the slotValue property to retrieve resolutions for either single or multiple values.

Resolutions object

slotValue

A SlotValue object that represents the value or values captured by the slot.

SlotValue object

source

Shows that the value came from the user. Always USER.

String

value

Included when the user provided a single value for the slot (slotValue.type is Simple). A string that represents the value the user spoke for the slot. This string is the actual value the user spoke, not necessarily the canonical value or one of the synonyms defined for the entity. Omitted when slotValue.type is List.

This property is provided for backwards-compatibility and can only contain a single slot value. Use the slotValue property to retrieve either single or multiple values.

String

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.

Name Description Type

resolutionsPerAuthority[]

An array of objects that represent 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 that represents the status of entity resolution for the slot.

Object

resolutionsPerAuthority[].status.code

A code that indicates the results of attempting to resolve the user utterance against the defined slot types. For details, see Entity resolution status codes.

Enum

resolutionsPerAuthority[].values

An array of resolved values for the slot. The values in the array are ordered from the most likely to least likely matches. Therefore, the first value in the array is considered the best match.

Array

resolutionsPerAuthority[].values[].value

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

Object

resolutionsPerAuthority[].values[].value.id

The unique ID defined for the resolved slot value. This ID is based on the IDs defined in the slot type definition. For details about how to define slot values and IDs, see Entity Resolution for Custom Slot Types.

String

resolutionsPerAuthority[].values[].value.name

The string for the resolved slot value.

String

SlotValue object

A SlotValue object contains either value or values, but never both. When the user provides a single value for the slot, the value is in the value property. When the user provides multiple values for the slot, the array of values is in the values property.

For details about configuring a slot to collect multiple values, see Collect Multiple Values in a Slot.

Name Description Type

resolutions

Included when the type is Simple. A Resolutions object that represents the results of resolving the words captured from the user's utterance.

Included for slots that use a custom slot type or a built-in slot type that you have extended with your own values.

Resolutions object

type

The type of value the slot captured from the user. Simple when the slot value is a single value, List when the slot value is an array of values.

String

value

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

This value is the same as the Slot object value property.

String

values

Included when the type is List. An array of SlotValue objects that represent the set of values the user provided. Each object in the array has its own type, value, and resolutions.

Array of SlotValue objects

Entity resolution status codes

  • ER_SUCCESS_MATCH – The spoken value successfully resolved to a known entity.
    • For a custom slot type, this means the value matched at least one value or synonym explicitly defined in the slot type
    • For a built-in slot type that you extended, the value matched at least one value or synonym in the set of extended values you added.
    • For a built-in slot type that supports entity resolution, the value resolved to at least one entity in the Alexa knowledge graph.
  • ER_SUCCESS_NO_MATCH – The spoken value didn't resolve to a known entity.
  • ER_ERROR_TIMEOUT – An error occurred due to a timeout.
  • ER_ERROR_EXCEPTION – An error occurred due to an exception during processing.

Valid Response Types

Your service can respond to IntentRequest with any combination of:

  • Standard response properties (outputSpeech, card, and reprompt).

  • Any AudioPlayer directive.

    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.

  • Any Dialog directive.

    For Dialog.Delegate: When dialogState is COMPLETED, you must also set updatedIntent to a different intent. If updatedIntent is not present or is set to the original intent, returning Dialog.Delegate for a COMPLETED dialog causes an error. When dialogState is either STARTED OR IN_PROGRESS, updatedIntent can be set to either the original intent or a new intent.

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" or "quit".
  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_SERVICE_ERROR, ENDPOINT_TIMEOUT).
  • 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": {
        "deviceId": "string",
        "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:

Was this page helpful?

Last updated: Nov 28, 2023