System 2.0

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

Sample Object

{
  "type": "AlexaInterface",
  "interface": "System",
  "version": "2.0",
  "configurations": {
    "locales": ["{{STRING}}", ...],
    "localeCombinations": [
      ["{{STRING}}", ...],
      ["{{STRING}}", ...],
      ...
    ]
  }
}

locales

The locales list informs Alexa of the locales that a device supports when operating 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. (See SetLocales, LocalesChanged, 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 operating 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. (See SetLocales, LocalesChanged, 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

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.

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

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

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

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

ReportSoftwareInfo

The ReportSoftwareInfo directive instructs a device to report current software information to Alexa using the SoftwareInfo event.

Sample 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

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": [
    // 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. For additional information see Context.

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.

Sample 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

<td markdown="span"Universally unique identifier (UUID) generated to the [RFC 4122](https://tools.ietf.org/html/rfc4122) specification.</td>
Parameter Description Type
messageIdstring

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.

Sample 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.)

Sample 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 do not 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

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.

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

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 is not processed the device receives 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 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" is not 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.

Sample 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. For additional information see Context.

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.