System 2.1
The System interface exposes functionality that pertains to the basic system-level operation of an Alexa Built-in device.
Version changes
- ADDED support for following locale combinations
["ar-SA","en-US"]
["en-US","ar-SA"]
- ADDED support for following locale combinations
["de-DE","it-IT"]
["it-IT","de-DE"]
["hi-IN","en-GB"]
["en-GB","hi-IN"]
["fr-FR","de-DE"]
["de-DE","fr-FR"]
- New network information setting
- ADDED
NetworkInfoReport
event - ADDED
NetworkInfoChanged
event
- ADDED
Capability assertion
A device can implement System 2.1 on its own behalf, but not on behalf of any connected endpoints.
New AVS integrations must assert support through Alexa.Discovery, but AVS continues support for legacy integrations through the Capabilities API.
Example object
{ "type": "AlexaInterface", "interface": "System", "version": "2.1", "configurations": { "locales": ["{{STRING}}", ...], "localeCombinations": [ ["{{STRING}}", ...], ["{{STRING}}", ...], ... ] } }
locales
The locales
list informs Alexa of the locales that a device supports when it operates in single-locale mode. End users are able to set the device locale from the locales
list, which appears in the payloads of the messages related to locale settings. (For more details, see SetLocales
, LocalesChanged
, and LocalesReport
.)
Parameter | Description | Type |
---|---|---|
locales |
Device-supported locales in single-locale mode. | list |
locales[i] |
A locale identifier from the following list:de-DE , en-AU , en-CA , en-GB , en-IN , en-US , es-ES , es-MX , es-US , fr-CA , fr-FR , hi-IN , it-IT , ja-JP , pt-BR , ar-SA
|
BCP-47 string |
localeCombinations
The localeCombinations
list informs Alexa of the locale combinations that a device supports when it operates in multi-locale mode. End users are able to set the device primary and secondary locales from the localeCombinations
list, which appears in the payloads of the messages related to locale settings. (For more details, see SetLocales
, LocalesChanged
, and LocalesReport
.)
localeCombinations
is an unordered list of ordered locales
lists. The inner lists of locale combinations use the first element to signify primary or default locale for the device. The primary locale operates as though it were set in single-locale mode for device-generated content, such as locally cached voice responses for offline mode or visual assets.
Parameter | Description | Type |
---|---|---|
localeCombinations |
Device-supported locale combinations in multi-locale mode. | list |
localeCombinations[i] |
Simultaneously supported locale combinations, where the first item is the primary locale and the next items are secondary locales. The following combinations are permitted:["en-US", "es-US"] ["es-US", "en-US"] ["en-US", "fr-FR"] ["fr-FR", "en-US"] ["en-US", "de-DE"] ["de-DE", "en-US"] ["en-US", "ja-JP"] ["ja-JP", "en-US"] ["en-US", "it-IT"] ["it-IT", "en-US"] ["en-US", "es-ES"] ["es-ES", "en-US"] ["en-IN", "hi-IN"] ["hi-IN", "en-IN"] ["fr-CA", "en-CA"] ["en-CA", "fr-CA"] ["en-GB", "fr-FR"] ["fr-FR", "en-GB"] ["en-GB", "es-ES"] ["es-ES", "en-GB"] ["en-GB", "de-DE"] ["de-DE", "en-GB"] ["en-GB", "it-IT"] ["it-IT", "en-GB"] ["hi-IN", "en-US"] ["en-US", "hi-IN"] ["pt-BR", "en-US"] ["en-US", "pt-BR"] ["es-MX", "en-US"] ["en-US", "es-MX"] ["de-DE", "it-IT"] ["it-IT", "de-DE"] ["hi-IN", "en-GB"] ["en-GB", "hi-IN"] ["fr-FR", "de-DE"] ["de-DE", "fr-FR"] ["ar-SA", "en-US"] ["en-US", "ar-SA"]
|
list |
localeCombinations[i][0] |
The primary locale for the device, either by using the SetLocales directive or reported to Alexa through the LocalesChanged event. When set, render the content and behavior generated by the device for the primary locale, as though it were operating in single-locale mode. |
BCP-47 string |
localeCombinations[i][j] |
j > 0 . The secondary locales the device might render based on assets provided at runtime by Alexa. |
BCP-47 string |
Directives
SetTimeZone
Alexa sends the SetTimeZone
directive to the device to instruct it to set its time zone. For example, if a user sets the time zone in the Alexa companion app, the device sends the TimeZoneReport
event in response to the SetTimeZone
directive.
Example message
{ "directive": { "header": { "namespace": "System", "name": "SetTimeZone", "messageId": "{{STRING}}" }, "payload": { "timeZone": "{{STRING}}" } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
timeZone |
The time zone for the device. Accepted Values: Olson format defined in the Timezone Database Example Value: America/Chicago
|
TZ string |
ReportState
The ReportState
directive instructs the device to reply with the StateReport
event, listing the values of all settings that follow the per-interface settings paradigm.
The settings that define events following the {SettingName}Report
naming convention specify their participation in their individual descriptions.
Example message
{ "directive": { "header": { "namespace": "System", "name": "ReportState", "messageId": "{{STRING}}" }, "payload": { } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
Universally unique identifier (UUID) generated to the RFC 4122 specification. | string |
SetLocales
Alexa sends the SetLocales
directive to the device to set the device locale(s), such as when a user sets the locale(s) in the Alexa companion app. The device must send the LocalesReport
event in response to the SetLocales
directive.
Example message
{ "directive": { "header": { "namespace": "System", "name": "SetLocales", "messageId": "{{STRING}}" }, "payload": { "locales": ["{{STRING}}", ...] } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
Unique ID used to represent a specific message. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
locales |
The locale(s) for the device. In single-locale mode, contains one locale string. In multi-locale mode, the first string indicates the primary locale, and any other strings correspond to secondary locales. | list |
locales[0] |
The primary locale for the device. Whether in single-locale or multi-locale mode, the first value determines the locale for device-generated content, such as locally cached voice responses for offline mode or visual assets. The device asserted possible values through the locales and localeCombintations configuration parameters.
|
BCP-47 string |
locales[i] |
For i > 0 , the secondary locale(s) for the device, which inform the device which secondary locales Alexa is listening for in user utterances. Alexa might generate audio and visual content for other directives, such as Speak , for these locales.Secondary locales don't impact device operation, but they might influence localization in GUIs, such as device screens or your companion app, for informational or user selection purposes. The device asserts possible values through the localeCombintations configuration parameter.
|
BCP-47 string |
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 the ResetUserInactivity
directive.
Example 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 |
ReportSoftwareInfo
The ReportSoftwareInfo
directive instructs a device to report current software information to Alexa using the SoftwareInfo
event.
Example message
{ "directive": { "header": { "namespace": "System", "name": "ReportSoftwareInfo", "messageId": "{{STRING}}" }, "payload": { } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A universally unique identifier (UUID) generated to the RFC 4122 specification. | string |
Events
TimeZoneReport
The TimeZoneReport
event is sent by the device in response to a SetTimeZone
directive sent by Alexa. For time zone changes initiated by the device, including when the change is first triggered by a peripheral, such as a companion app, the TimeZoneChanged
event must be sent instead.
Send the TimeZoneReport
event in cases of both success and failure, reporting the time zone actually set on the device after processing the SetTimeZone
directive.
Include the event
object, without the messageId
in its header
, in the StateReport
event's states
list when responding to the ReportState
directive.
Example message
{ "event": { "header": { "namespace": "System", "name": "TimeZoneReport", "messageId": "{{STRING}}" }, "payload": { "timeZone": "{{STRING}}" } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
timeZone |
The time zone for the device. Accepted Values: Olson format defined in the Timezone Database Example Value: America/Chicago
|
TZ string |
TimeZoneChanged
The device sends the TimeZoneChanged
event when the device initiates a time zone change. Such changes include those triggered by peripherals, such as third-party companion apps that instruct the device to change its time zone without otherwise informing Alexa directly. For time zone changes initiated by Alexa via the SetTimeZone
directive, the TimeZoneReport
event must be sent instead.
Example message
{ "event": { "header": { "namespace": "System", "name": "TimeZoneChanged", "messageId": "{{STRING}}" }, "payload": { "timeZone": "{{STRING}}" } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
timeZone |
The time zone for the device. Accepted Values: Olson format defined in the Timezone Database Example Value: America/Chicago
|
Olson TZ string |
SynchronizeState
The SynchronizeState
event must be sent to update AVS on the state of all product components when a new connection is established.
Example message
{ "context": [ // An array of context objects communicates 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 |
Unique ID used to represent a specific message. | string |
Payload parameters
Send an empty payload.
StateReport
Send the StateReport
event in response to the ReportState
directive, listing the values of all settings that follow the per-interface settings paradigm.
The settings that define events following the {SettingName}Report
naming convention specify their participation in their individual descriptions.
Example message
{ "event": { "header": { "namespace": "System", "name": "StateReport", "messageId": "{{STRING}}" }, "payload": { "states": [ { "header": { "namespace": "{{STRING}}", "name": "{{STRING}}" }, "payload": { // The settings fields defined by // the namespace and name combination } }, // other settings ] } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
Universally unique identifier (UUID) generated to the RFC 4122 specification. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
states |
The list of all settings and their values that the device maintains through the per-interface settings paradigm. | list |
states[i] |
An event object of an{SettingName}Report event for an individual setting, without the messageId in the header .Example Value:
{
"header": {
"namespace": "System",
"name": "LocalesReport"
},
"payload": {
"locales": ["en-US"]
}
}
|
object |
states[i]. header |
The header object, containing only namespace and name .
|
object |
states[i]. header. namespace |
Interface namespace of the setting. Example Value: System
|
string |
states[i]. header. name |
Name of the {SettingName}Report event of the setting.Example Value: LocalesReport
|
string |
states[i]. payload |
The payload defined by the {SettingName}Report event for the setting.Example Value: "locales": ["en-US"] as defined by the LocalesReport event in the System namespace
|
object |
LocalesReport
The LocalesReport
event is sent by the device in response to a SetLocales
directive sent by Alexa. For locale changes initiated by the device, including when the change is first triggered by a peripheral, such as a companion app, the LocalesChanged
event must be sent instead.
Send the LocalesReport
event in cases of both success and failure, reporting the locales actually set on the device after processing the SetLocales
directive.
Include the event
object, without the messageId
in its header
, in the StateReport
event states
list when responding to the ReportState
directive.
Example message
{ "event": { "header": { "namespace": "System", "name": "LocalesReport", "messageId": "{{STRING}}" }, "payload": { "locales": ["{{STRING}}", ...] } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
Unique ID used to represent a specific message. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
locales |
The device locale(s). In single-locale mode, contains one locale string. In multi-locale mode, the first string indicates the primary locale, and other strings correspond to secondary locales. | list |
locales[0] |
The primary locale for the device. Whether in single-locale or multi-locale mode, the first value determines the locale for device-generated content, such as locally cached voice responses for offline mode or visual assets. The device asserts possible values through the locales and localeCombintations configuration parameters.
|
BCP-47 string |
locales[i] |
For i > 0 , the secondary locale(s) for the device that Alexa is listening for in user utterances. Alexa might generate audio and visual content for these locales for other directives, such as Speak .Secondary locales don't impact device operation, but they might influence localization for GUIs, such as device screens or your companion app, for informational or user selection purposes. The device asserts possible values through the localeCombintations configuration parameter.
|
BCP-47 string |
LocalesChanged
The device sends the LocalesChanged
event when it initiates a locale change. Such changes include those triggered by peripherals, such as third-party companion apps that instruct the device to change its locale(s) without otherwise informing Alexa directly. For locale changes initiated by Alexa via the SetLocales
directive, the LocalesReport
event must be sent instead.
Example message
{ "event": { "header": { "namespace": "System", "name": "LocalesChanged", "messageId": "{{STRING}}" }, "payload": { "locales": ["{{STRING}}", ...] } } }
Header parameters
Parameter | Description | Type |
---|---|---|
messageId |
A unique ID used to represent a specific message. | string |
Payload parameters
Parameter | Description | Type |
---|---|---|
locales |
The locale(s) for the device. In single-locale mode, one locale string is present. In multi-locale mode, the first string indicates the primary locale, and strings that follow represent secondary locales. | list |
locales[0] |
The primary locale for the device. Whether in single-locale or multi-locale mode, the first value determines the locale for device-generated content, such as locally cached voice responses for offline mode or visual assets. The device asserts possible values through the locales and localeCombintations configuration parameters.
|
BCP-47 string |
locales[i] |
For i > 0 , the secondary locale(s) for the device, which Alexa is listening for in user utterances. Alexa might generate localized audio and visual content for other directives, such as Speak , for these locales.Secondary locales don't impact device operation, but they might influence localization for GUIs, such as device screens or your companion app, for informational or user selection purposes. The device asserts possible values through the localeCombintations configuration parameter.
|
BCP-47 string |
NetworkInfoReport
The optional NetworkInfoReport
event reports metadata about the device's network connection. This metadata enables network management experiences for end users, such as displaying network connection information in the Alexa companion app, and assists in diagnostics and troubleshooting.
Because there is no corresponding SetNetworkInfo
directive, under the Per-Interface Settings paradigm, your device should never directly send this event. Instead, include the event
object in the states
list of the StateReport
event, in response to the ReportState
directive.
networkInfo
object are not cumulative. Each time your device reports the networkInfo
object, previously stored data is overwritten. A property that was previously reported and omitted in a subsequent report will later return a blank value.Example message
{ "event": { "header": { "namespace": "System", "name": "NetworkInfoReport", "messageId": "{{STRING}}" }, "payload": { "networkInfo": { "connectionType": "{{STRING}}", "ESSID": "{{STRING}}", "BSSID": "{{STRING}}", "IPAddress": "{{STRING}}", "subnetMask": "{{STRING}}", "MACAddress": "{{STRING}}", "DHCPServerAddress": "{{STRING}}", "staticIP": {{BOOLEAN}} } } } }
Payload parameters
Parameter | Description | Type |
---|---|---|
networkInfo |
A set of network properties that are individually optional. | object |
networkInfo. connectionType |
Whether the device has a wired or wireless connection. Accepted Values: ETHERNET , WIFI
|
string |
networkInfo. ESSID |
The extended service set identifier. This is often called the "SSID" or "wifi network name." Example Value: MyHomeWifiNetwork
|
string |
networkInfo. BSSID |
The basic service set identifier (MAC address of the wifi access point). Example Value: a1:b2:c3:d4:e5:f6
|
string |
networkInfo. IPAddress |
The IP address of the device. Example Value: 192.168.0.47
|
string |
networkInfo. subnetMask |
The subnet mask for the local network. Example Value: 255.255.255.0
|
string |
networkInfo. MACAddress |
The MAC address (hardware identifier) of the device's network hardware. Example Value: a1:b2:c3:d4:e5:f6
|
string |
networkInfo. DHCPServerAddress |
If staticIP is false , the IP address of the DHCP server that assigned the device's IPAddress . This is often the router.Example Value: 192.168.0.1
|
string |
networkInfo. staticIP |
Whether the device has a statically defined IP address. Static IP reservations configured on the DHCP server are transparent to the device, and the value will be false in that case.Accepted Values: true , false
|
boolean |
NetworkInfoChanged
The optional NetworkInfoChanged
event reports metadata about the device's network connection. Send it when any configuration property changes. This metadata enables network management experiences for end users, such as displaying network connection information in the Alexa companion app, and assists in diagnostics and troubleshooting.
networkInfo
object are not cumulative. Each time your device reports the networkInfo
object, previously stored data is overwritten. A property that was previously reported and omitted in a subsequent report will later return a blank value.Example message
{ "event": { "header": { "namespace": "System", "name": "NetworkInfoChanged", "messageId": "{{STRING}}" }, "payload": { "networkInfo": { "connectionType": "{{STRING}}", "ESSID": "{{STRING}}", "BSSID": "{{STRING}}", "IPAddress": "{{STRING}}", "subnetMask": "{{STRING}}", "MACAddress": "{{STRING}}", "DHCPServerAddress": "{{STRING}}", "staticIP": {{BOOLEAN}} } } } }
Payload parameters
Parameter | Description | Type |
---|---|---|
networkInfo |
A set of network properties that are individually optional. | object |
networkInfo. connectionType |
Whether the device has a wired or wireless connection. Accepted Values: ETHERNET , WIFI
|
string |
networkInfo. ESSID |
The extended service set identifier. This is often called the "SSID" or "wifi network name." Example Value: MyHomeWifiNetwork
|
string |
networkInfo. BSSID |
The basic service set identifier (MAC address of the wifi access point). Example Value: a1:b2:c3:d4:e5:f6
|
string |
networkInfo. IPAddress |
The IP address of the device. Example Value: 192.168.0.47
|
string |
networkInfo. subnetMask |
The subnet mask for the local network. Example Value: 255.255.255.0
|
string |
networkInfo. MACAddress |
The MAC address (hardware identifier) of the device's network hardware. Example Value: a1:b2:c3:d4:e5:f6
|
string |
networkInfo. DHCPServerAddress |
If staticIP is false , the IP address of the DHCP server that assigned the device's IPAddress . This is often the router.Example Value: 192.168.0.1
|
string |
networkInfo. staticIP |
Whether the device has a statically defined IP address. Static IP reservations configured on the DHCP server are transparent to the device, and the value will be false in that case.Accepted Values: true , false
|
boolean |
UserInactivityReport
The device sends the UserInactivityReport
event after one hour of inactivity, and every hour after that until a user action is taken. The UserInactivityReport
provides Alexa with the duration since the last user activity was detected. A user activity is 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
.Example 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
The SoftwareInfo
event communicates device software information to Alexa, such as firmware version. It must be sent in these scenarios:
- For devices with persistent memory, send the event when the device initially boots 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 Alexa is able to process the event, the device receives a 204
HTTP status code with an empty body. If the event isn't processed, the device receives a 500
HTTP status code and an Exception Message from Alexa.
Example message
{ "event": { "header": { "namespace": "System", "name": "SoftwareInfo", "messageId": "{{STRING}}" }, "payload": { "firmwareVersion": "{{STRING}}" } } }
Header parameters
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 the device sends an invalid value to Alexa, Alexa returns an HTTP 400 status code to the device.Important: 0 isn't a valid firmware version.
|
string |
ExceptionEncountered
Your client must send the ExceptionEncountered
event when unable to run a directive from AVS.
Example message
{ "context": [ // An array of context objects that 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 |
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. |
Related topics
Last updated: Nov 27, 2023