Alexa.StepSpeaker Interface 3

Implement the Alexa.StepSpeaker interface in your Alexa add-on so that users can control the volume of their entertainment devices that contain audio speakers. For details about entertainment device add-ons, see Connect Your Device Cloud with Smart Home Add-ons for Entertainment Devices. Implement this interface for devices that make incremental discrete step adjustments to volume, where the range of volume isn’t known. For example, StepSpeaker can increase or decrease the volume by a step of 5, but can’t adjust the volume to 50 percent. If your device can set the volume to any integer value in a continuous range of values, implement the Speaker interface instead. For the list of languages that the Alexa.StepSpeaker interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

The Alexa.StepSpeaker interface uses the pre-built voice interaction model. After the user says one of these utterances, Alexa sends a corresponding directive to your add-on. The following examples show some user utterances:

Dutch
English (All)
German
Italian
Spanish (All)

Reportable properties

The Alexa.StepSpeaker interface doesn’t define any reportable properties.

Discovery

You describe endpoints that support Alexa.StepSpeaker by using the standard discovery mechanism described in Alexa.Discovery. Use SPEAKER, TV, STREAMING_DEVICE, GAME_CONSOLE, or other appropriate display category. For the full list of display categories, see display categories. To let Alexa know the health of your device, also implement the Alexa.EndpointHealth interface.

Discover response example

The following example shows a Discover.Response message for a speaker device that supports the Alexa.StepSpeaker and Alexa.PowerController interfaces. For the full list of recommended interfaces for an entertainment device, see Smart Home Device Templates.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "Unique identifier, preferably a version 4 UUID"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "Unique ID of the endpoint",
          "manufacturerName": "Manufacturer of the endpoint",
          "description": "Smart Speaker by Speaker Maker",
          "friendlyName": "Computer speaker",
          "displayCategories": ["SPEAKER"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.StepSpeaker",
              "version": "3",
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

Alexa sends the following Alexa.StepSpeaker interface directives to your add-on.

AdjustVolume

Support the AdjustVolume directive so that users can adjust the volume on their devices. The following examples show user utterances:

Dutch
English (All)
German
Italian
Spanish (All)

AdjustVolume directive example

The following example shows an AdjustVolume directive that Alexa sends to your add-on.

{
  "directive": {
    "header": {
      "namespace": "Alexa.StepSpeaker",
      "name": "AdjustVolume",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {
      "volumeSteps": 20
    }
  }
}

AdjustVolume directive payload

The following table shows the payload details for the AdjustVolume directive.

Property	Description	Type
`volumeSteps`	The amount by which to increase or decrease the volume, relative to the current volume. Valid values are -100 to 100, and positive values increase the volume and negative values decrease the volume.	Integer

AdjustVolume response

If you handle an AdjustVolume directive successfully, respond with an Alexa.Response event. A successful response confirms that the endpoint completed the requested action. The StepSpeaker interface defines no properties, but if you implement other interfaces, include the values of all properties in the context object. The following example shows an AdjustVolume response.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

AdjustVolume directive error handling

If you can’t handle an AdjustVolume directive successfully, respond with an Alexa.ErrorResponse event.

SetMute directive

Support the SetMute directive so that users can mute and unmute their devices. The following examples show user utterances:

Dutch
English (All)
German
Italian
Spanish (All)

SetMute directive example

The following example shows a SetMute directive that Alexa sends to your add-on.

{
  "directive": {
    "header": {
      "namespace": "Alexa.StepSpeaker",
      "name": "SetMute",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {
      "mute": true
    }
  }
}

SetMute directive payload

The following table shows the payload details for the SetMute directive

Property	Description	Type
`mute`	True to mute the device, false to unmute the device.	Boolean

SetMute response

If you handle a SetMute directive successfully, respond with an Alexa.Response event. A successful response confirms that the endpoint completed the requested action. The StepSpeaker interface defines no properties, but if you implement other interfaces, include the values of all properties in the context object. The following example shows a SetMute response.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

SetMute directive error handling

If you can’t handle a SetMute directive successfully, respond with an Alexa.ErrorResponse event.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Utterances

Reportable properties

Discovery

Discover response example

Directives

AdjustVolume

AdjustVolume directive example

AdjustVolume directive payload

AdjustVolume response

AdjustVolume directive error handling

SetMute directive

SetMute directive example

SetMute directive payload

SetMute response

SetMute directive error handling

​Utterances

​Reportable properties

​Discovery

​Discover response example

​Directives

​AdjustVolume

​AdjustVolume directive example

​AdjustVolume directive payload

​AdjustVolume response

​AdjustVolume directive error handling

​SetMute directive

​SetMute directive example

​SetMute directive payload

​SetMute response

​SetMute directive error handling

​Related topics

Utterances

Reportable properties

Discovery

Discover response example

Directives

AdjustVolume

AdjustVolume directive example

AdjustVolume directive payload

AdjustVolume response

AdjustVolume directive error handling

SetMute directive

SetMute directive example

SetMute directive payload

SetMute response

SetMute directive error handling

Related topics