Your Alexa Dashboards Settings

System Interface

The System interface exposes events which span multiple client components.

SynchronizeState Event

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

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 Event

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

ResetUserInactivity Directive

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 Directive

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

  • A user’s country settings are not supported by the endpoint they have connected to. For example, if a user’s current country 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 settings (or address). For example, if a user connected to the US endpoint changes their current country 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 settings. The endpoint URL may include the protocol and/or port.
For example: https://avs-alexa-na.amazon.com
string

SoftwareInfo Event

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 An ordinal 32-bit integer that must be 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"
  • 123
  • 8701
  • "50.3"
  • "avs-123.4x"
  • "ask.201-(1.23.4-test)"
string

ReportSoftwareInfo Directive

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

ExceptionEncountered Event

Your client must send this event when it is unable to execute 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. 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 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.

Additional Interfaces

Jump to the top of this document. Use the sidebar to navigate to additional interfaces.

Resources