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": {
        "supportedInterfaces": {
          "AudioPlayer": {}
        }
      },
      "application": {
        "applicationId": "amzn1.ask.skill.[unique-value-here]"
      },
      "user": {
        "userId": "amzn1.ask.account.[unique-value-here]",
        "accessToken": "Atza|AAAAAAAA...",
        "permissions": {
          "consentToken": "ZZZZZZZ..."
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    },
    "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

version

The version specifier for the request with the value defined as: "1.0"

string

session

The session object provides additional context associated with the request.

For the definition of the session object, see Session Object.

object

context

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 (LaunchRequest and IntentRequest), the context object duplicates the user and application information that is also available in the session.

For the definition of the context object, see Context Object.

object

request

A request object that provides the details of the user’s request. There are several different request types avilable, see:

object

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

de-DE

German

en-GB

English (UK)

en-IN

English (India)

en-US

English (US)

For more about supporting multiple languages, see Develop Skills in Multiple Languages.

For details about each type of request object your skill may receive, see:

Session Object

Standard request types (LaunchRequest, IntentRequest, and SessionEndedRequest) include the session object.

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

new

A boolean value indicating whether this is a new session. Returns true for a new session or false for an existing session.

boolean

sessionId

A string that represents a unique identifier per a user’s active session.

string

attributes

A map of key-value pairs. The attributes map is empty for requests where a new session has started with the property new set to true.

  • The key is a string that represents the name of the attribute. Type: string
  • The value is an object that represents the value of the attribute. Type: object

When returning your response, you can include data you need to persist during the session in the sessionAttributes property. The attributes you provide are then passed back to your skill on the next request.

map

application

An object containing an application ID. This is used to verify that the request was intended for your service:

  • applicationId: A string representing the appliation ID for your skill.

This information is also available in the context.System.application property.

Your skill’s application ID is displayed on the Skill Information page in the developer portal.

object

user

An object that describes the user making the request. A user is composed of:

  • userId: A string that represents a unique identifier for the user who made the request. The length of this identifier can vary, but is never more than 255 characters. The userId is automatically generated when a user enables the skill in the Alexa app.

  • accessToken: a token identifying the user in another system. This is only provided if the user has successfully linked their account. See Linking an Alexa User with a User in Your System for more details.

  • permissions: contains a consentToken allowing the skill access to information that the customer has consented to provide, such as address information. See Permissions for more details.

The accessToken field will not appear if null, and the permissions object also will not appear if consentToken is null.

This information is also available in the context.System.application property.

object

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 (LaunchRequest and IntentRequest), the context object duplicates the user and application information that is also available in the session object.

Parameter Description Type

System

A system object that provides information about the current state of the Alexa service and the device interacting with your skill.

For the definition of the system object, see System Object.

object

AudioPlayer

An object providing the current state for the AudioPlayer interface. For the definition of the AudioPlayer object, see AudioPlayer Object.

Note that 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.

object

System Object

Parameter Description Type

application

An object containing an application ID. This is used to verify that the request was intended for your service:

  • applicationId: A string representing the appliation ID for your skill.

This information is also available in the session.application property for LaunchRequest, IntentRequest, and SessionEndedRequest types.

Your skill’s application ID is displayed on the Skill Information page in the developer portal.

object

user

An object that describes the user making the request. A user is composed of:

  • userId: A string that represents a unique identifier for the user who made the request. The length of this identifier can vary, but is never more than 255 characters. The userId is automatically generated when a user enables the skill in the Alexa app.

  • accessToken: a token identifying the user in another system. This is only provided if the user has successfully linked their account. See Linking an Alexa User with a User in Your System for more details.

  • permissions: contains a consentToken allowing the skill access to information that the customer has consented to provide, such as address information. See Permissions for more details.

The accessToken field will not appear if null, and the permissions object also will not appear if consentToken is null.

This information is also available in the session.user property for LaunchRequest, IntentRequest, and SessionEndedRequest types.

object

device

An object providing information about the device used to send the request. The device object contains both deviceId and supportedInterfaces properties:

  • The deviceId property uniquely identifies the device.
  • The supportedInterfaces property lists each interface that the device supports. For example, if supportedInterfaces includes AudioPlayer {}, then you know that the device supports streaming audio using the AudioPlayer interface.

object

apiEndpoint

An object that references the correct base URI to refer to by region. The base URI for US calls for device address data is: https://api.amazonalexa.com/. The base URI for UK and DE calls for device address data is: https://api.eu.amazonalexa.com.

object

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

token

An opaque token that represents the audio stream described by this AudioPlayer object. You provide this token when sending the Play directive. This is only included in the AudioPlayer object when your skill was the skill most recently playing audio on the device.

string

offsetInMilliseconds

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 AudioPlayer object when your skill was the skill most recently playing audio on the device.

long

playerActivity

playerActivity: Indicates the last known state of audio playback:

  • IDLE: Nothing was playing, no enqueued items.
  • PAUSED: Stream was paused.
  • PLAYING: Stream was playing.
  • BUFFER_UNDERRUN: Buffer underrun
  • FINISHED: Stream was finished playing.
  • STOPPED: Stream was interrupted.

string

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 outputSpeech response cannot exceed 8000 characters.
  • All of the text included in a card cannot exceed 8000 characters. This includes the title, content, text, and image URLs.
  • An image URL (smallImageUrl or largeImageUrl) cannot exceed 2000 characters.
  • The token included in an audioItem.stream for the AudioPlayer.Play directive cannot exceed 1024 characters.
  • The url included in an audioItem.stream for the AudioPlayer.Play directive cannot exceed 8000 characters.
  • The total size of your response cannot exceed 24 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",
      "ssml": "<speak>SSML text string to speak</speak>"
    },
    "card": {
      "type": "Standard",
      "title": "Title of the card",
      "content": "Content of a simple 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",
        "ssml": "<speak>SSML text string to speak</speak>"
      }
    },
    "directives": [
      {
        "type": "InterfaceName.Directive"
        (...properties depend on the directive type)
      }
    ],
    "shouldEndSession": true
  }
}

Response Parameters

Parameter Description Type Required

version

The version specifier for the response with the value to be defined as: "1.0"

string

Yes

sessionAttributes

A map of key-value pairs to persist in the session.

  • The key is a string that represents the name of the attribute. Type: string.
  • The value is an object that represents the value of the attribute. Type: object.

Session attributes are ignored if included on a response to an AudioPlayer or PlaybackController request.

map

No

response

A response object that defines what to render to the user and whether to end the current session.

object

Yes

Response Object

Parameter Description Type Required

outputSpeech

The object containing the speech to render to the user. See OutputSpeech Object.

object

No

card

The object containing a card to render to the Amazon Alexa App. See Card Object.

object

No

reprompt

The object containing the outputSpeech to use if a re-prompt is necessary.

This is used if the your service keeps the session open after sending the response, but the user does not respond with anything that maps to an intent defined in your voice interface while the audio stream is open.

If this is not set, the user is not re-prompted.

object

No

shouldEndSession

A boolean value with true meaning that the session should end after Alexa speaks the response, or false if the session should remain active. If not provided, defaults to true.

Boolean

No

directives

An array of directives specifying device-level actions to take using a particular interface, such as the AudioPlayer interface for streaming audio. For details about the directives you can include in your response, see:

array

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 LaunchRequest or IntentRequest.

Parameter Description Type Required

type

A string containing the type of output speech to render. Valid types are:

  • "PlainText": Indicates that the output speech is defined as plain text.
  • "SSML": Indicates that the output speech is text marked up with SSML.

string

Yes

text

A string containing the speech to render to the user. Use this when type is "PlainText"

string

Yes (for PlainText)

ssml

A string containing text marked up with SSML to render to the user. Use this when type is "SSML"

string

Yes (for SSML)

Card Object

This object can only be included when sending a response to a LaunchRequest or IntentRequest.

Parameter Description Type Required

type

A string describing the type of card to render. Valid types are:

  • "Simple": A card that contains a title and plain text content.
  • "Standard": A card that contains a title, text content, and an image to display.
  • "LinkAccount": a card that displays a link to an authorization URL that the user can use to link their Alexa account with a user in another system. See Linking an Alexa User with a User in Your System for details.

string

Yes

title

A string containing the title of the card. (not applicable for cards of type LinkAccount).

string

No

content

A string containing the contents of a Simple card (not applicable for cards of type Standard or LinkAccount).

string

No

text

A string containing the text content for a Standard card (not applicable for cards of type Simple or LinkAccount)

string

No

image

An image object that specifies the URLs for the image to display on a Standard card. Only applicable for Standard cards.

You can provide two URLs, for use on different sized screens.

  • smallImageUrl
  • largeImageUrl

See Including a Card in Your Skill’s Response.

object

No

Reprompt Object

This object can only be included when sending a response to a LaunchRequest or IntentRequest.

Parameter Description Type Required
outputSpeech An OutputSpeech object containing the text or SSML to render as a re-prompt. object No

Errors

InternalServerError

  • An error occurred while handling a request within your service.
  • HTTP Status Code: 500

Response Examples

Standard Response to 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)

{
  "version": "1.0",
  "sessionAttributes": {
    "supportedHoriscopePeriods": {
      "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
  }
}

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

See Display Interface Reference.

Service Interface Reference (JSON)

Request Format and Standard Request Types:

Interfaces: