Alexa Interface Message and Property Reference

When you create an Alexa skill and implement the Alexa interface in your skill code, you can send and receive the basic set of Alexa messages. These messages include general Alexa directives and responses, discovery, state reporting, change reporting, and error reporting. Alexa sends directives to your skill to request something on behalf of the user. If your skill controls a device, Alexa can send directives to control the device, or to request state information about the device. You respond to directives by sending responses to Alexa. You can also send events to Alexa proactively.

This reference includes the list of Alexa foundational messages and parameters that all skills implement.

Message reference

Messages from Alexa to your skill

The following list includes messages that Alexa sends to your skill:

• AcceptGrant directive – Alexa gives you credentials that identify and authenticate the customer to Alexa.
• Discover directive – The customer asks Alexa to connect their device to your smart home skill.
• ReportState directive – Alexa wants to announce or display the state of a device connected to your smart home or video skill.
• Interface-specific directives – The user asks Alexa to control their device. For examples of directives, see the documentation for each interface.

Messages from your skill to Alexa

The following list includes event messages that your skill sends to Alexa:

• AcceptGrant.Response – After you successfully receive and store credentials for the user, you send an accept grant response.
• Discover.Response – You send discover responses so that users can connect their devices to your skill.
• AddOrUpdateReport event – After the user adds or updates a device connected to your skill, you send the event to let Alexa know about the new or updated device.
• DeleteReport event – After the user deletes a device connected to your smart home skill, you send the event to let Alexa know.
• StateReport – You send state reports to respond to report state directives to let Alexa know the state of the devices that your skill controls.
• ChangeReport event – You send change report events to proactively report when the state of a device changes.
• Response event – You send responses to interface-specific directives.
• DeferredResponse event – You send a deferred response event after certain directives to notify Alexa that your actual response comes later.
• ErrorResponse – If you can't handle interface-specific directives successfully, you send error responses to indicate the failure reason. For example, if you receive a turn on directive, but the device isn't plugged in.

Examples of all events and responses that you send to Alexa are provided in the documentation for each interface.

Message format

All directives, events, and responses share the same message contents:

• Header — Defines the message and the interface.
• Endpoint — Identifies the device and includes authentication information.
• Payload — Message parameters. Contents of the payload vary based on the interface defined in the header.

For directives, these properties are part of the Directive object. For events and responses, these properties are part of the Event object. In addition, some events and responses contain the Context object.

The following example shows a directive request. The message includes the header, endpoint, and payload objects.

The following example shows a directive response. The message includes the header, endpoint, payload, and context objects.

Property reference

The following properties are the same across all message types.

Header object

The following table shows the properties that you include in the Header object.

Property	Description	Type	Required
namespace	Identifies the interface of the message payload. For example, Alexa, Alexa.Discovery, Alexa.PowerController.	String	Yes
name	Name of the directive, event, or response in the message. For example Discover, ReportState, TurnOn, AdjustPercentage, Response, ErrorResponse, StateReport, ChangeReport.	String	Yes
messageId	Unique identifier for the message. Include a new value in every response and event that your skill sends. Amazon recommends using a version 4 UUID. Use for tracking purposes. You can log the message ID, but don't use the message ID to program business logic. Valid value: String of alphanumeric characters and dashes up to 128 characters.	String	Yes
correlationToken	Opaque token that identifies the directive message exchange. If you receive a directive from Alexa that includes a correlation token, include the same correlation token in your response message. When you send a response asynchronously to the Alexa event gateway, you also include the correlation token that you received from Alexa. If you send an event that isn't in response to a request from Alexa, don't include the correlation token. For example, you don't include a correlationToken when you send an Alexa.ChangeReport event.	String	No
payloadVersion	Version of the interface specified in the namespace field. Valid value: "3"	String	Yes

Endpoint object

If your skill controls a device, messages from and to Alexa contain an Endpoint object. Messages from your skill to Alexa include an Endpoint object to help Alexa identify the device and authenticate your skill. For details about the definition of the Endpoint object in a discovery response, see the endpoint object.

The following table shows the properties included in the Endpoint object.

Property	Description	Type	Required
endpointId	Identifier for the endpoint. The identifier must be unique across all devices owned by the user within the domain of the skill. You provide the endpointID during discovery, and you must use the same identifier consistently in all messages that target the same device. Valid value: Up to 256 characters. Can include letters, numbers, spaces, and the following special characters: _ - = # ; : ? @ &	String	Yes
scope	Bearer token scope to authenticate the skill. Required for events and asynchronous responses sent to the Alexa gateway.	Scope object	No
cookie	List of key-value pairs associated with the endpoint. You provide the cookies during discovery and Alexa returns them in each message to your skill for the endpoint. Valid values: Up to 5000 bytes	List of JSON-formatted strings	No

Scope object

The Scope object provides authorization and identifying info for a message. The object can appear in the payload, for example in the discover directive, or in an endpoint object, for example in asynchronous response messages.

The Scope object is required for messages that you send to the Alexa event gateway.

The following table shows the properties included in the Scope object.

Property	Description	Type	Required
type	Provides the scope type of the token. Valid values: BearerToken, BearerTokenWithPartition	String	Yes
token	OAuth 2.0 bearer token to identify and access a linked customer account.	String	Yes
partition	Location target for the request, such as a room name or number. Valid for BearerTokenWithPartition only.	String	No
userId	Unique identifier for the user who made the request. Don't rely on this value to identify users. Use token instead. Valid for BearerTokenWithPartition only.	String	No

BearerToken scope

The BearerToken scope type provides an OAuth bearer token for accessing a linked customer account or identifying an Alexa customer. You receive the token during authentication. Typically used for smart home and video skills.

The following example shows a BearerToken scope.

BearerTokenWithPartition scope

The BearerTokenWithPartition scope type provides an OAuth bearer token for accessing a linked user account and specifying a physical location. Typically used for skills that target Alexa for Business.

The following example shows a BearerTokenWithPartition scope.

Directive object

All directives include the Directive object.

Property	Description	Type	Required
header	Identifies the message and interface.	Header object	Yes
endpoint	Identifies the endpoint that the user wants to control and provides authorization to authenticate Alexa.	Endpoint object	Yes
payload	Identifies properties that are part of the directive.	Payload object	Yes

Event object

All events and responses to directives include the Event object.

Property	Description	Type	Required
header	Identifies the event and interface.	Header object	Yes
endpoint	Identifies the endpoint and provides authorization to authenticate your skill.	Endpoint object	Yes
payload	Identifies the properties that changed. If the message doesn't include a payload, set to an empty object.	Payload object	Yes

Context object

The Context object contains a list all reportable properties of the endpoint. To include a property, you must define the property as retrievable = true in your discovery response. Amazon recommends that you specify the state of all the properties of the endpoint, including the properties that didn't change.

Property	Description	Type	Required
properties	Identifies the retrievable properties of the endpoint. Include one Property object for each property reported.	Array of Property objects	No

Payload object

The payload varies for each directive, response, and event. For details about the payload properties, see the interface documentation for each interface that your device supports.

Property object

The Property object defines a reportable property of the endpoint. Each Alexa interface defines the property name and value. For details, see the documentation for each interface that you support in your Alexa skill.

The following table shows the Property object parameters.

Property	Description	Type	Required
namespace	Name of the Alexa capability interface to which the property belongs, such as, Alexa.PowerController.	String	Yes
instance	Name of the interface instance that you defined in the discovery response. For generic controller interfaces only. For example, Dryer.Temperature.	String	No
name	Name of the reported property that belongs to the namespace.	String	Yes
value	Value of the reported property. Each Alexa interface defines the type of the value field.	Various	Yes
timeOfSample	Time the endpoint detected the state change. Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.	String	Yes
uncertaintyInMilliseconds	Uncertainty of the timeOfSample field in milliseconds. This field represents the number of milliseconds after the endpoint last confirmed the property value. For example, if the endpoint sampled the property value 60 seconds ago, you set uncertaintyInMilliseconds to 60000.	Number	Yes

Cause object

The Cause object describes the reason that caused the reported event. The Cause object is included in interfaces that define events.

The following table shows the Cause object properties.

Property	Description	Type	Required
type	Identifies what caused the change.	Type string	Yes

Type values

Use one of the following type values to describe the reason for the event.

Cause type	Description
APP_INTERACTION	Customer interaction with a device app. For example, a customer switches on a light or locks a door by using an app provided by the device vendor.
PERIODIC_POLL	Periodic poll of an endpoint. For example, you might poll a temperature sensor every hour and send the updated temperature to Alexa.
PHYSICAL_INTERACTION	Physical interaction with an endpoint. For example, the user turned on a light or locked a door lock manually.
VOICE_INTERACTION	Any user interaction with Alexa. For example, a user turns on a light by speaking to their Echo device, or a user turns off the light by using their Alexa app.

Related topics

• Capability Property Schemas
• Friendly Name Resources and Assets