System 2.1

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

Version changes

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
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-IN", "hi-IN"]
["hi-IN", "en-IN"]
["fr-CA", "en-CA"]
["en-CA", "fr-CA"]
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] For 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

RevokeAuthorization

The RevokeAuthorization directive instructs the client to clear all Login With Amazon (LWA) authorization tokens stored on a device.

Example message

{
    "directive": {
        "header": {
            "namespace": "System",
            "name": "RevokeAuthorization",
            "messageId": "{{STRING}}"
        },
        "payload": {
         }
    }
}

Header parameters

Parameter Description Type
messageId A unique ID used to represent a specific message. 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

{
  "directive": {
    "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

{
  "directive": {
    "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.

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.

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 execute 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 execute 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 execute 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.