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 properties 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. And, the example includes the Advertising property.
{
"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..."
}
},
"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..."
},
"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..."
},
"Advertising": {
"advertisingId": "296D263C-87BC-86A3-18A7-D307393B83A9",
"limitAdTracking": false
},
"AudioPlayer": {
"playerActivity": "PLAYING",
"token": "audioplayer-token",
"offsetInMilliseconds": 0
}
},
"request": {}
}
Request body properties
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.
| Property | Description | Type |
|---|---|---|
|
|
Version specifier for the request with the value defined as: |
|
|
|
Provides additional context associated with the request. 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 |
|
|
|
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 ( For the definition of the context object, see Context Object. |
|
|
|
Provides the details of the user's request. There are several different request types available, see: 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) |
|
|
Dutch (NL) |
|
|
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.
| Property | Description | Type |
|---|---|---|
|
|
Indicates whether this is a new session. Returns |
|
|
|
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. |
|
|
|
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 |
|
|
|
Contains 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 Copy Skill ID link for the skill. |
|
|
|
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.
| Property | Description | Type |
|---|---|---|
|
|
(Optional) Provides the customer's advertising ID and preference for receiving interest-based ads. Included in requests to skills that declare that the skill delivers advertising. |
|
|
|
Provides information about the Alexa Presentation Language document currently displayed on the screen. Included in the request when the user's device has a screen and the screen is displaying an APL document your skill sent with the |
|
|
|
Provides the current state for the Note that |
|
|
|
Provides information about the current state of the Alexa service and the device interacting with your skill. |
|
|
|
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
| Property | Description | Type |
|---|---|---|
|
|
Contains a token that can be used to access Alexa-specific APIs. This token encapsulates:
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 |
|
|
|
References the correct base URI to refer to by region, for use with APIs such as the Device Settings API and Progressive Response API. |
|
|
|
Contains an application ID. Use the ID 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. |
|
|
|
Provides information about the device used to send the request. The
|
|
|
|
Represents a logical construct organizing actors (such as people and organizations) and resources (such as devices and skills) that interact with Alexa systems. A
|
|
|
|
Describes the person who is making the request to Alexa. The A
The |
|
|
|
Describes the Amazon account for which the skill is enabled. The A
The This information is also available in the |
|
Advertising object
The Advertising object provides the customer's advertising ID and preference for receiving interest-based ads. Alexa includes the Advertising object in requests to custom skills that declare that the skill delivers advertising. For more details, see About Alexa Advertising ID.
To receive Alexa advertising IDs, you must indicate that your skill delivers advertising, publish a privacy policy, and submit your skill for recertification. For more details, see Steps to Add Alexa Advertising ID to Your Skill.
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Customer-resettable, unique identifier that maps to the Formatted as a version 4 UUID string separated by dashes (8-4-4-4-12). |
String |
Yes |
|
|
Indicates whether the customer wants to receive interest-based ads. Set to |
Boolean |
Yes |
Examples
The following examples show settings that indicate that the customer opted out of interest-based ads and tracking.
"Advertising": {
"advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
"limitAdTracking": true
}
"Advertising": {
"advertisingId": "00000000-0000-0000-0000-00000000",
"limitAdTracking": true
}
The following example shows settings that indicate that the customer opted in to interest-based ads and tracking.
"Advertising": {
"advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
"limitAdTracking": false
}
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.
| Property | 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 KB.
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 properties
| Propert | Description | Type | Required |
|---|---|---|---|
|
|
Version specifier for the response with the value to be
defined as: |
|
Yes |
|
|
Map of key-value pairs to persist in the session.
Session attributes are ignored if included in a response to an |
|
No |
|
|
Defines what to render to the user and whether to end the current session. |
Yes |
Response object
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Speech to render to the user. See OutputSpeech Object. |
|
No |
|
|
Card to render to the Amazon Alexa App. See Card Object. |
|
No |
|
|
Used if your service keeps the session open after sending the response ( If the |
|
No |
|
|
Indicates what should happen after Alexa speaks the response:
Responses to |
|
No |
|
|
List 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.
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Type of output speech to render.
|
|
Yes |
|
|
Speech to render to the user. Use this property when |
|
Yes (for |
|
|
Text marked up with SSML to render to the user. Use this when |
|
Yes (for |
|
|
Determines the queuing and playback of this output speech.
|
|
No |
Card object
This object can only be included when sending a response to a CanFulfillIntentRequest, LaunchRequest, IntentRequest, or InputHandlerEvent.
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Describes the type of card to render. Valid types are:
|
|
Yes |
|
|
Title of the card. (not applicable for cards of type |
|
No |
|
|
Contents of a Tip: To include line breaks, use either
\r\n or \n within the content of the card. |
|
No |
|
|
Text content for a Tip: To include line breaks, use either
\r\n or \n within the text of the card. |
|
No |
|
|
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.
| Property | Description | Type | Required |
|---|---|---|---|
|
|
|
|
No |
|
|
List 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 properties 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: Sep 10, 2024