Merci de votre visite. Cette page est disponible en anglais uniquement.

System Interface

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

    Version Changes

    Capabilities API

    To use version 2.0 of the System interface, it must be declared in your call to the Capabilities API.

    Sample Object

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

    locales

    This list informs Alexa of the locales that a device supports when operating in single-locale mode. End users will be able to set the device's locale from this list, which will appear in the payloads of the messages pertaining 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

    This list informs Alexa of the locale combinations that a device supports when operating in multi-locale mode. End users will be able to set the device's primary and secondary locales from this list, which will appear in the payloads of the messages pertaining to locale settings. (See SetLocales, LocalesChanged, LocalesReport.)

    Note that this is an unordered list of ordered 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 subsequent 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 the device can be set to, either through the SetLocales directive or reported to Alexa through the LocalesChanged event. When set, content and behavior generated by the device must be rendered in this locale, as though it were operating in single-locale mode. BCP-47 string
    localeCombinations[i][j] For j > 0, the secondary locales the device may 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": [
        // 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.

    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 will specify in their individual descriptions whether they participate in this mechanic.

    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

    The StateReport event is sent 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 will specify in their individual descriptions whether they participate in this mechanic.

    Sample Message

    {
      "event": {
        "header": {
          "namespace": "System",
          "name": "StateReport",
          "messageId": "{{STRING}}"
        },
        "payload": {
          "states": [
            {
              "header": {
                "namespace": "{{STRING}}",
                "name": "{{STRING}}"
              },
              "payload": {
                // The settings fields defined by
                // this 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 This is the interface namespace of the setting.

    Example Value: System
    string
    states[i].header.name This is the name of the {SettingName}Report event of the setting.

    Example Value: LocalesReport
    string
    states[i].payload This is 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

    The SetLocales directive will be sent by Alexa to the device to instruct it to set its locale(s). This may result from an end user's setting the locale(s) in the Alexa companion app. The device must send the LocalesReport event in response to this 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) the device must be set to. In single-locale mode, one locale string will be present. In multi-locale mode, the first string indicates the primary locale, and subsequent strings indicate secondary locales. list
    locales[0] The (primary) locale the device must be set to. Whether in single-locale or multi-locale mode, this first value determines the locale for device-generated content, such as locally cached voice responses for offline mode or visual assets.

    Possible values are previously asserted by the device through the locales and localeCombintations configuration parameters.
    BCP-47 string
    locales[i] For i > 0, the secondary locale(s) the device must be set to. These inform the device what additional locales Alexa is listening for in end user utterances and therefore, in which locales Alexa may generate audio and visual content for other directives (such as Speak).

    Secondary locales do not impact device operation with respect to locale, but they may be surfaced in GUIs (such as device screens or your companion app) for informational or user selection purposes.

    Possible values are previously asserted by the device 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.)

    This event must be sent both in cases of success and failure, reporting the locales actually set on the device after processing the SetLocales directive.

    The event object, without the messageId in its header, must be included 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 locale(s) the device is set to. In single-locale mode, one locale string will be present. In multi-locale mode, the first string indicates the primary locale, and subsequent strings indicate secondary locales. list
    locales[0] The (primary) locale the device is set to. Whether in single-locale or multi-locale mode, this first value determines the locale for device-generated content, such as locally cached voice responses for offline mode or visual assets.

    Possible values are previously asserted by the device through the locales and localeCombintations configuration parameters.
    BCP-47 string
    locales[i] For i > 0, the secondary locale(s) the device is set to. These inform the device what additional locales Alexa is listening for in end user utterances and therefore, in which locales Alexa may generate audio and visual content for other directives (such as Speak).

    Secondary locales do not impact device operation with respect to locale, but they may be surfaced in GUIs (such as device screens or your companion app) for informational or user selection purposes.

    Possible values are previously asserted by the device through the localeCombintations configuration parameter.
    BCP-47 string

    LocalesChanged Event

    The LocalesChanged event is sent by the device when a locale change is initiated by the device. 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) the device is set to. In single-locale mode, one locale string will be present. In multi-locale mode, the first string indicates the primary locale, and subsequent strings indicate secondary locales. list
    locales[0] The (primary) locale the device is set to. Whether in single-locale or multi-locale mode, this first value determines the locale for device-generated content, such as locally cached voice responses for offline mode or visual assets.

    Possible values are previously asserted by the device through the locales and localeCombintations configuration parameters.
    BCP-47 string
    locales[i] For i > 0, the secondary locale(s) the device is set to. These inform the device what additional locales Alexa is listening for in end user utterances and therefore, in which locales Alexa may generate audio and visual content for other directives (such as Speak).

    Secondary locales do not impact device operation with respect to locale, but they may be surfaced in GUIs (such as device screens or your companion app) for informational or user selection purposes.

    Possible values are previously asserted by the device through the localeCombintations configuration parameter.
    BCP-47 string

    SetTimeZone Directive

    The SetTimeZone directive will be sent by Alexa to the device to instruct it to set its time zone. This may result from an end user's setting the time zone in the Alexa companion app. The device must send the TimeZoneReport event in response to this 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 the device must be set to.

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

    This event must be sent both in cases of success and failure, reporting the time zone actually set on the device after processing the SetTimeZone directive.

    The event object, without the messageId in its header, must be included 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 the device is set to.

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

    Example Value: America/Chicago
    TZ string

    TimeZoneChanged Event

    The TimeZoneChanged event is sent by the device when a time zone change is initiated by the device. 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 the device is set to.

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

    Example Value: America/Chicago
    Olson TZ string

    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

    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

    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

    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

    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 AVS device.

      Version Changes

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

      Capabilities API

      To use version 1.2 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.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 AVS device.

        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 functionality that pertains to the basic system-level operation of an AVS device.

          Version Changes

          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.