System 2.1

The System interface exposes functionality that pertains to the basic system-level operation of an Alexa Built-in device.

Version changes

New network information setting
- ADDED NetworkInfoReport event
- ADDED NetworkInfoChanged event

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.

Important: System 2.1 is incompatible with Settings 1.0. If your device declares support for System 2.1, don't implement or declare support for Settings 1.0.

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"]`	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.

Note: Successive reports of the 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.

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.

Tip: The value provided for 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.

Valid	Invalid
"123" "8701" "20170207"	"50.3" "avs-123.4x" "ask.201-(1.23.4-test)"

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.

Last updated: Sep 28, 2022

System 2.1

Version changes

Capability assertion

locales

localeCombinations

Directives

SetTimeZone

ReportState

SetLocales

ResetUserInactivity

ReportSoftwareInfo

Events

TimeZoneReport

TimeZoneChanged

SynchronizeState

StateReport

LocalesReport

LocalesChanged

NetworkInfoReport

NetworkInfoChanged

UserInactivityReport

SoftwareInfo

ExceptionEncountered

Related topics