Vielen Dank für Ihren Besuch. Diese Seite ist momentan nur auf Englisch verfügbar. Wir arbeiten an der deutschen Version. Vielen Dank für Ihr Verständnis.

System Interface

    The System interface exposes events which span multiple client components.

    Version Changes

    Capabilities API

    To use version 1.1 of the System interface, it must be declared in your call to the Capabilities API. For additional details, see Capabilities API.

    Sample Object

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

    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/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

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

    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.

      The System interface exposes events which span multiple client components.

      Version Changes

      • A documentation error has been corrected. The SoftwareInfo event and ReportSoftwareInfo directive have been moved to version 1.1 of the System interface. Use the version selector at the top of this page to toggle versions.

      Capabilities API

      To use version 1.0 of the System interface, it must be declared in your call to the Capabilities API. For additional details, see Capabilities API.

      Sample Object

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

      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/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

      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.