System 1.2

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

Capability assertion

System 1.2 may be implemented by the device on its own behalf, but not on behalf of any connected endpoints.

New AVS integrations must assert support through Alexa.Discovery, but Alexa will continue to support existing integrations using the Capabilities API.

Sample Object

{
    "type": "AlexaInterface",
    "interface": "System",
    "version": "1.2"
}

Directives

ResetUserInactivity

The ResetUserInactivity directive is sent to your client to reset the inactivity timer used by UserInactivityReport. For example, a user interaction on the Amazon Alexa app would trigger this directive.

Sample Message

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

Header Parameters

Parameter Description Type
messageId A unique ID used to represent a specific message. string

SetEndpoint

The SetEndpoint directive instructs a client to change endpoints when the following conditions are met:

  • A user's country/region settings are not supported by the endpoint they have connected to. For example, if a user's current country/region is set to the United Kingdom (UK) in Manage Your Content and Devices and the client connects to the United States (US) endpoint, a SetEndpoint directive will be sent instructing the client to connect to the endpoint that supports the UK.
  • A user changes their country/region settings (or address). For example, if a user connected to the US endpoint changes their current country/region from the US to the UK, a SetEndpoint directive will be sent instructing the client to connect to the endpoint that supports the UK.

Sample Message


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

Header Parameters

Parameter Description Type
messageId A unique ID used to represent a specific message. string

Payload Parameters

Parameter Description Type
endpoint The AVS endpoint URL that supports your user's country/region settings. The endpoint URL may include the protocol and/or port.
For example: https://avs-alexa-na.amazon.com 		string

ReportSoftwareInfo

This directive instructs your product to report current software information to Alexa using the SoftwareInfo event.

Sample Message


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

Header Parameter

Parameter Description Type
messageId A universally unique identifier (UUID) generated to the RFC 4122 specification. string

Events

SynchronizeState

The SynchronizeState event must be sent to update AVS on the state of all product components when a new connection is established.

Sample Message

{
    "context": [
        // This is an array of context objects that are used to communicate the
        // state of all client components to Alexa. See Context for details.     
    ],      
    "event": {
        "header": {
            "namespace": "System",
            "name": "SynchronizeState",
            "messageId": "{{STRING}}"
        },
        "payload": {
        }
    }
}

Context

This event requires your product to report the status of all client component states to Alexa in the context object.

Header Parameters

Parameter Description Type
messageId A unique ID used to represent a specific message. string

Payload Parameters

An empty payload should be sent.

UserInactivityReport

This event must be sent after an hour of inactivity, and every hour after that until a user action is taken. This provides Alexa with the duration since the last user activity was detected. A user activity is defined as an action that confirms a user is in the presence of the product, such as interacting with on-product buttons, speaking with Alexa, or using a GUI affordance. After a user activity is detected, the timer used to track inactivity must be reset to 0.

Sample Message

{
   "event": {
        "header": {
            "namespace": "System",
            "name": "UserInactivityReport",
            "messageId": "{{STRING}}"
        },
        "payload": {
            "inactiveTimeInSeconds": {{LONG}}
        }

    }

}

Header Parameters

Parameter Description Type
messageId A unique ID used to represent a specific message. string

Payload Parameters

Parameter Description Type
inactiveTimeInSeconds Time in seconds since the last user interaction. long

SoftwareInfo

This event communicates your product's software information to Alexa, such as firmware version. It must be sent in these scenarios:

  • For products with persistent memory, the event must be sent on the product's initial boot and whenever the firmware version is updated.
  • For products without persistent memory, the event must be sent on each boot/reboot.
  • When a ReportSoftwareInfo directive is received.

If the event is successfully processed, the product will receive a 204 HTTP status code with an empty body. If the event is not processed the product will receive a 500 HTTP status code and an Exception Message from Alexa.

Sample Message


{    
    "event": {
        "header": {
            "namespace": "System",
            "name": "SoftwareInfo",
            "messageId": "{{STRING}}"
        },
        "payload": {
            "firmwareVersion": "{{STRING}}"
        }
    }
}

Header Parameter

Parameter Description Type
messageId A universally unique identifier (UUID) generated to the RFC 4122 specification. string

Payload Parameters

Parameter Description Type
firmwareVersion A positive signed 32-bit integer represented as a string. If an invalid value is sent to Alexa, an HTTP 400 status code is returned to your client. IMPORTANT: "0" is not a valid firmware version.
Valid Invalid
  • "123"
  • "8701"
  • "20170207"
  • "50.3"
  • "avs-123.4x"
  • "ask.201-(1.23.4-test)"
string

ExceptionEncountered

Your client must send this event when it is unable to run a directive from AVS.

Sample Message

{
    "context": [
        // This is an array of context objects that are used to communicate the
        // state of all client components to Alexa. See Context for details.      
    ],     
    "event": {
        "header": {
            "namespace": "System",
            "name": "ExceptionEncountered",
            "messageId": "{{STRING}}"
        },
        "payload": {
            "unparsedDirective": "{{STRING}}",
            "error": {
                "type": "{{STRING}}"
                "message": "{{STRING}}"
            }
        }
    }
}

Context

This event requires your product to report the status of all client component states to Alexa in the context object.

Header Parameters

Parameter Description Type
messageId A unique ID used to represent a specific message. string

Payload Parameters

Parameter Description Type
unparsedDirective When unable to run a directive, your client must return the directive to AVS as a string. string
error Key/value pairs for error. object
error.type An error your client must return to AVS when unable to run a directive. string
error.message Additional error details for logging and troubleshooting. string

Error Types

Error Type Description
UNEXPECTED_INFORMATION_RECEIVED The directive sent to your client was malformed or the payload does not conform to the directive specification.
INTERNAL_ERROR An error occurred while the device was handling the directive and the error does not fall into the specified categories.
Was this page helpful?

Last updated: Nov 27, 2023