Alexa.Gadget.StateListener Interface

Note: On December 31, 2021, we paused support for third-party device makers working with Alexa Gadgets, while we work to create an even better developer and customer experience. Please stay tuned to the Amazon developer portal for updates. In the interim, please visit the landing pages for Alexa Voice Service, Alexa Connect Kit, and Alexa Skills Kit to discover ways you can provide new customer experiences with voice.

This interface provides your gadget the status of the following Echo device-level features:

Setting and clearing of alerts (alarms, timers, and reminders).
Detection of the wake word. Note that pressing the "talk" or microphone button on an Echo device is not intended to trigger wake word detection.
(Beta) Time information from the Echo device. This is sent every 30 minutes.

Note: Each directive and event is a compilation of three separate .proto files: a header, a payload, and a file that combines the two. You can download the .proto files from the Alexa Gadgets Sample Code GitHub repository. In this topic, the .proto files combine all fields into one file for descriptive purposes.

Supporting this interface
Directives
- StateUpdate directive

Supporting this interface

To support this interface, the gadget must respond to the Echo device's Discover directive with a Discover.Response event that includes the following entry in its array of Capabilities:

Note: In the configuration, you can remove the supportedTypes that your gadget does not support. However, if you remove a supportedType, your gadget will not receive that type of status update.

{
   "type": "AlexaInterface",
   "interface": "Alexa.Gadget.StateListener",
   "version": "1.0",
   "configurations": {
      "supportedTypes":[
       {
          "name":"alarms"
       },
       {
          "name":"timers"
       },          
       {
          "name":"reminders"
       },         
       {
          "name":"wakeword"
       },     
       {
          "name":"timeinfo"
       }                
      ]
   }
 }

Directives

This interface includes one directive: StateUpdate, as described next.

StateUpdate directive

This directive provides the gadget with status information about the Echo device that it is communicating with. The .proto file contents are as follows:

message StateUpdateDirectiveProto {
   Directive directive = 1;
   message Directive {
      alexaGadgetStateListener.StateUpdateDirectivePayloadProto payload = 2;
      header.DirectiveHeaderProto header = 1;
   }
}

message DirectiveHeaderProto {
   string namespace = 1; 
   string name = 2; 
   string messageId = 3; 
   string dialogRequestId = 4;      
}

message StateUpdateDirectivePayloadProto {
   repeated States states = 1;
   message States {
      string name = 1;
      string value = 2;
   }
}

StateUpdateDirectiveProto

The fields in this message are as follows:

Field	Description	Type
`directive`	Contains a complete `StateUpdate` directive.	`Directive`

Directive

The fields of the message are as follows:

Field	Description	Type
`header`	Contains the header for this directive.	`DirectiveHeaderProto`
`payload`	Contains the payload for this directive.	`StateUpdateDirectivePayloadProto`

DirectiveHeaderProto

The fields of the message are as follows:

Field	Description	Type
`namespace`	The namespace of this directive, which is `Alexa.Gadget.StateListener`.	`string`
`name`	The name of this directive, which is `StateUpdate`.	`string`
`messageId`	An ID that uniquely defines an instance of this directive. This string can be empty.	`string`
`dialogRequestId`	A unique ID that correlates this directive with a specific voice interaction from a user. You can ignore this field.	`string`

StateUpdatePayloadProto

The fields of the message are as follows:

Field	Description	Type
`states`	Name/value pairs that specify the state type and value. The name is the type of state, such as `alarms`. The value is the value of the state, such as `cleared`.	`States`

States

The fields of the message are as follows:

Field	Description	Type
`name`	The type of state. Valid values are `alarms`, `timers`, `reminders`, `wakeword`, and `timeinfo` (Beta).	`string`
`value`	The value of the state, which depends on the type of state: For states with `name` equal to `alarms`, `timers`, `reminders`, or `wakeword`, the valid values are `active` and `cleared`. For the `timeinfo` state, the value is a string that contains the Echo device's time in ISO 8601 format.	`string`