System 1.2
The System interface exposes functionality that pertains to the basic system-level operation of an Alexa Built-in device.
Capability assertion
System 1.2 may be implemented by the device on its own behalf, but not on behalf of any connected endpoints.
New AVS integrations must assert support through Alexa.Discovery, but Alexa will continue to support existing integrations using the Capabilities API.
Sample Object
{ "type": "AlexaInterface", "interface": "System", "version": "1.2" }
Directives
ResetUserInactivity
The ResetUserInactivity
directive is sent to your client to reset the inactivity timer used by UserInactivityReport
. For example, a user interaction on the Amazon Alexa app would trigger this directive.
Sample Message
{ "directive": { "header": { "namespace": "System", "name": "ResetUserInactivity", "messageId": "{{STRING}}" }, "payload": { } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
SetEndpoint
The SetEndpoint
directive instructs a client to change endpoints when the following conditions are met:
- A user's country/region settings are not supported by the endpoint they have connected to. For example, if a user's current country/region is set to the United Kingdom (UK) in Manage Your Content and Devices and the client connects to the United States (US) endpoint, a
SetEndpoint
directive will be sent instructing the client to connect to the endpoint that supports the UK. - A user changes their country/region settings (or address). For example, if a user connected to the US endpoint changes their current country/region from the US to the UK, a
SetEndpoint
directive will be sent instructing the client to connect to the endpoint that supports the UK.
Sample Message
{ "directive": { "header": { "namespace": "System", "name": "SetEndpoint", "messageId": "{{STRING}}" }, "payload": { "endpoint": "{{STRING}}" } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
endpoint | The AVS endpoint URL that supports your user's country/region settings. The endpoint URL may include the protocol and/or port. For example: https://avs-alexa-na.amazon.com
|
string |
ReportSoftwareInfo
This directive instructs your product to report current software information to Alexa using the SoftwareInfo
event.
Sample Message
{ "directive": { "header": { "namespace": "System", "name": "ReportSoftwareInfo", "messageId": "{{STRING}}" }, "payload": { } } }
Header Parameter
Parameter | Description | Type |
---|---|---|
messageId | A universally unique identifier (UUID) generated to the RFC 4122 specification. | string |
Events
SynchronizeState
The SynchronizeState
event must be sent to update AVS on the state of all product components when a new connection is established.
Sample Message
{ "context": [ // This is an array of context objects that are used to communicate the // state of all client components to Alexa. See Context for details. ], "event": { "header": { "namespace": "System", "name": "SynchronizeState", "messageId": "{{STRING}}" }, "payload": { } } }
Context
This event requires your product to report the status of all client component states to Alexa in the context
object.
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
An empty payload should be sent.
UserInactivityReport
This event must be sent after an hour of inactivity, and every hour after that until a user action is taken. This provides Alexa with the duration since the last user activity was detected. A user activity is defined as an action that confirms a user is in the presence of the product, such as interacting with on-product buttons, speaking with Alexa, or using a GUI affordance. After a user activity is detected, the timer used to track inactivity must be reset to 0.
inactiveTimeInSeconds
should always be a multiple of 3600 (1 hour). For example, after 4 hours of inactivity the value would be 14400
.Sample Message
{ "event": { "header": { "namespace": "System", "name": "UserInactivityReport", "messageId": "{{STRING}}" }, "payload": { "inactiveTimeInSeconds": {{LONG}} } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
inactiveTimeInSeconds | Time in seconds since the last user interaction. | long |
SoftwareInfo
This event communicates your product's software information to Alexa, such as firmware version. It must be sent in these scenarios:
- For products with persistent memory, the event must be sent on the product's initial boot and whenever the firmware version is updated.
- For products without persistent memory, the event must be sent on each boot/reboot.
- When a
ReportSoftwareInfo
directive is received.
If the event is successfully processed, the product will receive a 204
HTTP status code with an empty body. If the event is not processed the product will receive a 500
HTTP status code and an Exception Message from Alexa.
Sample Message
{ "event": { "header": { "namespace": "System", "name": "SoftwareInfo", "messageId": "{{STRING}}" }, "payload": { "firmwareVersion": "{{STRING}}" } } }
Header Parameter
Parameter | Description | Type |
---|---|---|
messageId | A universally unique identifier (UUID) generated to the RFC 4122 specification. | string |
Payload Parameters
Parameter | Description | Type | ||||
---|---|---|---|---|---|---|
firmwareVersion | A positive signed 32-bit integer represented as a string. If an invalid value is sent to Alexa, an HTTP 400 status code is returned to your client. IMPORTANT: "0" is not a valid firmware version.
|
string |
ExceptionEncountered
Your client must send this event when it is unable to run a directive from AVS.
Sample Message
{ "context": [ // This is an array of context objects that are used to communicate the // state of all client components to Alexa. See Context for details. ], "event": { "header": { "namespace": "System", "name": "ExceptionEncountered", "messageId": "{{STRING}}" }, "payload": { "unparsedDirective": "{{STRING}}", "error": { "type": "{{STRING}}" "message": "{{STRING}}" } } } }
Context
This event requires your product to report the status of all client component states to Alexa in the context
object.
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
unparsedDirective | When unable to run a directive, your client must return the directive to AVS as a string. | string |
error | Key/value pairs for error. | object |
error.type | An error your client must return to AVS when unable to run a directive. | string |
error.message | Additional error details for logging and troubleshooting. | string |
Error Types
Error Type | Description |
---|---|
UNEXPECTED_INFORMATION_RECEIVED | The directive sent to your client was malformed or the payload does not conform to the directive specification. |
INTERNAL_ERROR | An error occurred while the device was handling the directive and the error does not fall into the specified categories. |