Request and Response JSON Reference
The Alexa Skills Kit enables you to give Alexa new abilities by building a cloud-based service. This service can be either a web service or an AWS Lambda function. This document details the protocol interface between the Alexa service and the web service or Lambda function you create. AWS Lambda is a service offering by Amazon Web Services.
Alexa communicates with your service via a request-response mechanism using HTTP over SSL/TLS. When a user interacts with an Alexa skill, your service receives a POST request containing a JSON body. The request body contains the parameters necessary for the service to perform its logic and generate a JSON-formatted response.
Request Format
This section documents the format for the requests sent to your service.
HTTP Header
POST / HTTP/1.1
Content-Type : application/json;charset=UTF-8
Host : your.application.endpoint
Content-Length :
Accept : application/json
Accept-Charset : utf-8
Signature:
SignatureCertChainUrl: https://s3.amazonaws.com/echo.api/echo-api-cert.pem
Request Body Syntax
The request body sent to your service is in JSON format. In this example, the AudioPlayer directive has been requested, but the Display.RenderTemplate and VideoApp.Launch directives have not been requested.
{
"version": "1.0",
"session": {
"new": true,
"sessionId": "amzn1.echo-api.session.[unique-value-here]",
"application": {
"applicationId": "amzn1.ask.skill.[unique-value-here]"
},
"attributes": {
"key": "string value"
},
"user": {
"userId": "amzn1.ask.account.[unique-value-here]",
"accessToken": "Atza|AAAAAAAA...",
"permissions": {
"consentToken": "ZZZZZZZ..."
}
}
},
"context": {
"System": {
"device": {
"deviceId": "string",
"supportedInterfaces": {
"AudioPlayer": {}
},
"persistentEndpointId" : "amzn1.alexa.endpoint.[unique-value-here]"
},
"application": {
"applicationId": "amzn1.ask.skill.[unique-value-here]"
},
"user": {
"userId": "amzn1.ask.account.[unique-value-here]",
"accessToken": "Atza|AAAAAAAA...",
"permissions": {
"consentToken": "ZZZZZZZ..."
}
},
"person": {
"personId": "amzn1.ask.person.[unique-value-here]",
"accessToken": "Atza|BBBBBBB..."
},
"unit": {
"unitId": "amzn1.ask.unit.[unique-value-here]",
"persistentUnitId" : "amzn1.alexa.unit.did.[unique-value-here]"
},
"apiEndpoint": "https://api.amazonalexa.com",
"apiAccessToken": "AxThk..."
},
"AudioPlayer": {
"playerActivity": "PLAYING",
"token": "audioplayer-token",
"offsetInMilliseconds": 0
}
},
"request": {}
}
Request Body Parameters
All requests include the version, context, and request objects at the top level. The session object is included for all standard requests, but it is not included for AudioPlayer, VideoApp, or PlaybackController requests.
| Parameter | Description | Type |
|---|---|---|
|
|
The version specifier for the request with the value defined as: |
|
|
|
The Note: The
session is included for all standard requests, but it is not included for AudioPlayer, VideoApp, or PlaybackController requests.For the definition of the |
|
|
|
The For the definition of the context object, see Context Object. |
|
|
|
A Standard Requests: Requests associated with a specific interface: |
|
Request Locale
Every request object includes a locale property. This is a string code indicating the user's locale, such as en-US for English (US). Use this to determine the language in which your skill should respond.
Supported locales:
| Locale code | Language |
|---|---|
|
|
Arabic (SA) |
|
|
German (DE) |
|
|
English (AU) |
|
|
English (CA) |
|
|
English (UK) |
|
|
English (IN) |
|
|
English (US) |
|
|
Spanish (ES) |
|
|
Spanish (MX) |
|
|
Spanish (US) |
|
|
French (CA) |
|
|
French (FR) |
|
|
Hindi (IN) |
|
|
Italian (IT) |
|
|
Japanese (JP) |
|
|
Portuguese (BR) |
For more about supporting multiple languages, see Develop Skills in Multiple Languages.
Session Object
Standard request types (CanFulfillIntentReqeuest, LaunchRequest, IntentRequest, and SessionEndedRequest) include the session object. The [GameEngine interface][game-engine-interface-reference] includes a session object also.
Requests from interfaces such as AudioPlayer and PlaybackController are not sent in the context of a session, so they do not include the session object. The context.System.user and context.System.application objects provide the same user and application information as the same objects within session – see Context Object.
| Parameter | Description | Type |
|---|---|---|
|
|
A boolean value indicating whether this is a new session. Returns |
|
|
|
A string that represents a unique identifier per a user's active session. Note: A
sessionId is consistent for multiple subsequent requests for a user and session. If the session ends for a user, then a new unique sessionId value is provided for subsequent requests for the same user. |
|
|
|
A map of key-value pairs. The attributes map is empty for requests where a new session has started with the property
When returning your response, you can include data you need to persist during the session in the |
|
|
|
An object containing an application ID. This is used to verify that the request was intended for your service:
This information is also available in the To see the application ID for your skill, navigate to the list of skills and click the View Skill ID link for the skill. |
|
|
|
An object that describes the Amazon account for which the skill is enabled. The A
The This information is also available in the |
|
Context Object
The context object provides your skill with information about the current state of the Alexa service and device at the time the request is sent to your service. This is included on all requests. For requests sent in the context of a session (CanFulfillIntentRequest, LaunchRequest and IntentRequest), the context object duplicates the user and application information that is also available in the session object.
| Parameter | Description | Type |
|---|---|---|
|
|
An object providing information about the Alexa Presentation Language document currently displayed on the screen. This is included when the user's device has a screen and an APL document was rendered on that screen when the user's action triggered a request to your skill. For more information about APL, see Add Visuals and Audio to Your Skill. |
|
|
|
An object providing the current state for the Note that |
|
|
|
A |
|
|
|
Included when the user's device has a screen. The |
|
|
|
Included when the user's device has a screen or a character display. Contains objects that provide information about the screens or displays available. For details, see Viewport object in the skill request in the Alexa.Presentation.APLT Interface Reference. |
|
System Object
| Parameter | Description | Type |
|---|---|---|
|
|
A
This token is included in all requests sent to your skill. When using this token to access an API that requires permissions, your skill should call the API and check the return code. If a |
|
|
|
A string that references the correct base URI to refer to by region, for use with APIs such as the Device Location API and Progressive Response API. |
|
|
|
An object containing an application ID. This is used to verify that the request was intended for your service:
This information is also available in the The application ID is displayed in the developer console. You can see it when you pick AWS Lambda ARN on the Custom > Endpoint page. It is also shown below the skill name in your list of skills. |
|
|
|
An object providing information about the device used to send the request. The
|
|
|
|
An object that represents a logical construct organizing actors (such as people and organizations) and resources (such as devices and skills) that interact with Alexa systems. A
|
|
|
|
An object that describes the person who is making the request to Alexa. The A
The |
|
|
|
An object that describes the Amazon account for which the skill is enabled. The A
The This information is also available in the |
|
AudioPlayer Object
This object provides the current state for the AudioPlayer interface.
AudioPlayer is included on all customer-initiated requests (such as requests made by voice or using a remote control), but includes the details about the playback (token and offsetInMilliseconds) only when sent to a skill that was most recently playing audio.
Requests that are not customer-initiated, such as the AudioPlayer requests do not include the AudioPlayer object in the context. For these requests, the request type indicates the current state (for example, the request AudioPlayer.PlaybackStarted indicates that the playback has started) and details about the state are part of the request object.
| Parameter | Description | Type |
|---|---|---|
|
|
An opaque token that represents the audio stream described by this |
|
|
|
Identifies a track's offset in milliseconds at the time the request was sent. This is 0 if the track is at the beginning. This is only included in the |
|
|
|
|
|
Response Format
This section documents the format of the response that your service returns. The service for an Alexa skill must send its response in JSON format.
Note the following size limitations for the response:
- The
outputSpeechresponse can't exceed 8000 characters. - All of the text included in a
cardcan't exceed 8000 characters. This includes thetitle,content,text, and image URLs. - An image URL (
smallImageUrlorlargeImageUrl) can't exceed 2000 characters. - When using the
<audio>SSML tag: - The
tokenincluded in anaudioItem.streamfor theAudioPlayer.Playdirective can't exceed 1024 characters. - The
urlincluded in anaudioItem.streamfor theAudioPlayer.Playdirective can't exceed 8000 characters. - The
payloadof aCustomInterfaceController.SendDirectivedirective can't exceed 1000 bytes. For details about this directive, see Respond to Alexa with a directive targeted to a gadget. - The total size of your response can't exceed 120 kilobytes.
If your response exceeds these limits, the Alexa service returns an error.
HTTP Header
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length:
Response Body Syntax
{
"version": "string",
"sessionAttributes": {
"key": "value"
},
"response": {
"outputSpeech": {
"type": "PlainText",
"text": "Plain text string to speak",
"playBehavior": "REPLACE_ENQUEUED"
},
"card": {
"type": "Standard",
"title": "Title of the card",
"text": "Text content for a standard card",
"image": {
"smallImageUrl": "https://url-to-small-card-image...",
"largeImageUrl": "https://url-to-large-card-image..."
}
},
"reprompt": {
"outputSpeech": {
"type": "PlainText",
"text": "Plain text string to speak",
"playBehavior": "REPLACE_ENQUEUED"
}
},
"directives": [
{
"type": "InterfaceName.Directive"
(...properties depend on the directive type)
}
],
"shouldEndSession": true
}
}
Response Parameters
| Parameter | Description | Type | Required |
|---|---|---|---|
|
|
The version specifier for the response with the value to be
defined as: |
|
Yes |
|
|
A map of key-value pairs to persist in the session.
Session attributes are ignored if included in a response to an |
|
No |
|
|
A response object that defines what to render to the user and whether to end the current session. |
|
Yes |
Response Object
| Parameter | Description | Type | Required |
|---|---|---|---|
|
|
The object containing the speech to render to the user. See OutputSpeech Object. |
|
No |
|
|
The object containing a card to render to the Amazon Alexa App. See Card Object. |
|
No |
|
|
The object containing the Used if your service keeps the session open after sending the response ( If the |
|
No |
|
|
A boolean value that indicates what should happen after Alexa speaks the response:
Responses to |
|
No |
|
|
An array of directives specifying device-level actions to take using a particular interface, such as the |
|
No |
OutputSpeech Object
This object is used for setting both the outputSpeech and the reprompt properties.
This object can only be included when sending a response to a CanFulfillIntentRequest, LaunchRequest, IntentRequest, Display.ElementSelected request or an InputHandlerEvent.
| Parameter | Description | Type | Required |
|---|---|---|---|
|
|
A string containing the type of output speech to render. Valid types are:
|
|
Yes |
|
|
A string containing the speech to render to the user. Use this when |
|
Yes (for |
|
|
A string containing text marked up with SSML to render to the user. Use this when |
|
Yes (for |
|
|
A string that determines the queuing and playback of this output speech. Valid values are:
For more information about |
|
No |
Card Object
This object can only be included when sending a response to a CanFulfillIntentRequest, LaunchRequest, IntentRequest, or InputHandlerEvent.
| Parameter | Description | Type | Required |
|---|---|---|---|
|
|
A string describing the type of card to render. Valid types are:
|
|
Yes |
|
|
A string containing the title of the card. (not applicable for cards of type |
|
No |
|
|
A string containing the contents of a Tip: To include line breaks, use either
\r\n or \n within the content of the card. |
|
No |
|
|
A string containing the text content for a Tip: To include line breaks, use either
\r\n or \n within the text of the card. |
|
No |
|
|
An You can provide two URLs, for use on different sized screens.
|
|
No |
Reprompt Object
The reprompt object is valid when sending a response to a CanFulfillIntentRequest, LaunchRequest, or IntentRequest.
Alexa speaks the reprompt when shouldEndSession is false and the user doesn't respond within a few seconds.
| Parameter | Description | Type | Required |
|---|---|---|---|
|
|
An OutputSpeech object containing the text or SSML to render as a re-prompt. |
|
No |
|
|
An array of directives specifying device-level actions to take using a particular interface. Within a
No other directives are supported within the |
|
No |
When both outputSpeech and directives are included, Alexa speaks the outputSpeech first and then plays the audio generated by the Alexa.Presentation.APLA.RenderDocument directive. When the directives array contains multiple Alexa.Presentation.APLA.RenderDocument directives, they play in array order.
Errors
InternalServerError
- An error occurred while handling a request within your service.
HTTPStatus Code: 500
Response Examples
Standard Response to CanFulfillIntentRequest, LaunchRequest or IntentRequest Example
This response does not use any interfaces (such as AudioPlayer), so it returns the standard response properties (outputSpeech, card, reprompt, and shouldEndSession). CanFulfillIntent includes extra parameters specific to that response.
{
"version": "1.0",
"sessionAttributes": {
"supportedHoroscopePeriods": {
"daily": true,
"weekly": false,
"monthly": false
}
},
"response": {
"outputSpeech": {
"type": "PlainText",
"text": "Today will provide you a new learning opportunity. Stick with it and the possibilities will be endless. Can I help you with anything else?"
},
"card": {
"type": "Simple",
"title": "Horoscope",
"content": "Today will provide you a new learning opportunity. Stick with it and the possibilities will be endless."
},
"reprompt": {
"outputSpeech": {
"type": "PlainText",
"text": "Can I help you with anything else?"
}
},
"shouldEndSession": false
}
}
See also: CanFulfillIntent Response to CanFulfillIntentRequest
Response with an Alexa Presentation Language (APL) directive
See the RenderDocument directive example in the Alexa.Presentation.APL Interface Reference.
Response to IntentRequest or Launch Request with Directives Example
This response includes AudioPlayer interface directives. In this example, Alexa would speak the provided outputSpeech text before beginning the audio playback.
Note that this example shows a response sent from a LaunchRequest or IntentRequest. A response returned from AudioPlayer or PlaybackController could not include the outputSpeech, card, reprompt, or shouldEndSession properties.
{
"version": "1.0",
"sessionAttributes": {},
"response": {
"outputSpeech": {
"type": "PlainText",
"text": "Playing the requested song."
},
"card": {
"type": "Simple",
"title": "Play Audio",
"content": "Playing the requested song."
},
"reprompt": {
"outputSpeech": {
"type": "PlainText",
"text": null
}
},
"directives": [
{
"type": "AudioPlayer.Play",
"playBehavior": "ENQUEUE",
"audioItem": {
"stream": {
"token": "this-is-the-audio-token",
"url": "https://my-audio-hosting-site.com/audio/sample-song.mp3",
"offsetInMilliseconds": 0
}
}
}
],
"shouldEndSession": true
}
}
Response to AudioPlayer or PlaybackController Example (Directives Only)
This is an example of a response sent from an AudioPlayer or PlaybackController request (such as a PlaybackController.NextCommandIssued request sent when the user pressed the Next button on a remote), so it cannot include the outputSpeech, card, reprompt, or shouldEndSession properties.
{
"version": "1.0",
"response": {
"directives": [
{
"type": "AudioPlayer.Play",
"playBehavior": "REPLACE_ALL",
"audioItem": {
"stream": {
"token": "track2-long-audio",
"url": "https://my-audio-hosting-site.com/audio/sample-song-2.mp3",
"offsetInMilliseconds": 0
}
}
}
]
}
}
Service Interface Reference (JSON)
Request Format and Standard Request Types:
- Request and Response JSON Reference (this document)
- Request Types Reference (LaunchRequest, IntentRequest, SessionEndedRequest)
- Alexa.Presentation.APL Interface
- Alexa.Presentation.APLT Interface
- Alexa.Presentation.HTML Interface
- AudioPlayer Interface
- Connections Interface
- Dialog Interface
- Messaging Interface
- PlaybackController Interface
- VideoApp Interface
Last updated: Mar 30, 2022