System

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

    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": [
        // 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 A unique ID used to represent a specific message. string

    Payload parameters

    Send an empty payload.

    ReportState directive

    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 parameter

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

    StateReport event

    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 parameter

    Parameter Description Type
    messageId A 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 individual setting's {SettingName}Report event, 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

    SetLocales directive

    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 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, 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. These inform the device which secondary locales Alexa is listening for in user utterances and therefore, in which locales Alexa might generate audio and visual content for other directives (such as Speak).

    Secondary locales do not impact device operation, but they might influence localizaiton 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

    LocalesReport event

    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's 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 A 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 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

    LocalesChanged event

    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

    SetTimeZone directive

    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.

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

    Possible Values: those in the "TZ database name" column

    Example Value: America/Chicago
    TZ string

    TimeZoneReport event

    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.

    Sample 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: those in the "TZ database name" column

    Example Value: America/Chicago
    TZ string

    TimeZoneChanged event

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

    Sample 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: those in the "TZ database name" column

    Example Value: America/Chicago
    Olson TZ string

    UserInactivityReport event

    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

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

    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 parameter

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

    SoftwareInfo event

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

    RevokeAuthorization directive

    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

    ExceptionEncountered event

    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.

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

      Version Changes

      • New functionality that allows the cloud to instruct a device to remove its association with a customer account:

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

      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.

      RevokeAuthorization Directive

      This directive instructs your 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

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

        Version Changes

        Capability Assertion

        System 1.1 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.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 functionality that pertains to the basic system-level operation of an Alexa Built-in device.

          Version Changes

          Capability Assertion

          System 1.0 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.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.