Home > Alexa > Alexa Skills Kit

Standard Request Types Reference

Intro

Introduction

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

If you implement the AudioPlayer and PlaybackController interfaces, your skill receives additional requests beyond the three standard request types. See AudioPlayer Interface and PlaybackController 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. 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.

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",
  "locale": "string",
  "intent": {
    "name": "string",
    "slots": {
      "string": {
        "name": "string",
        "value": "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
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. string

Intent Object

Parameter Description Type

name

A string representing the name of the intent.

string

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

Slot Object

Parameter Description Type
name A string that represents the name of the slot. string
value A string that represents the value of the slot. The value is not required.

Note that AMAZON.LITERAL slot values sent to your service are always in all lower case.
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.

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",
    "locale": "string",
    "intent": {
      "name": "GetZodiacHoroscopeIntent",
      "slots": {
        "ZodiacSign": {
          "name": "ZodiacSign",
          "value": "virgo"
        }
      }
    }
  }
}

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"
  }
}

Other Reference Materials

Interfaces: