Alexa.Speaker Interface 3

Implement the Alexa.Speaker 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 can set the volume to any integer value in a continuous range of values. If your device can only adjust the volume in discrete steps, implement the StepSpeaker interface instead. For the list of languages that the Alexa.Speaker 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.Speaker 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:

Reportable properties

The Alexa.Speaker interface supports the volume and muted properties. You identify that you support the properties in your discovery response.

Volume property

The Alexa.Speaker interface uses the volume property to represent the audio volume level of a device. The property is an integer and valid values from 0 to 100 inclusive. If the volume property is used to represent a change, then valid values are from –100 to 100 inclusive. In that case, a positive value increases the volume and a negative value decreases the volume. The following example shows the volume property.

{
   "name": "volume",
   "value": 50
}

Muted property

The Alexa.Speaker interface uses the muted property to indicate whether the audio of a device is muted or not. The property is a boolean. Set to true if the device is muted and set to false if the device isn’t muted. The following example shows the muted property.

{
    "name": "muted",
    "value": false
}

Discovery

You describe endpoints that support Alexa.Speaker by using the standard discovery mechanism described in Alexa.Discovery. Set retrievable to true for the properties that you report when Alexa sends your add-on a state report request. Set proactivelyReported to true for the properties that you proactively report to Alexa in a change report. 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.Speaker 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.Speaker",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "volume"
                  },
                  {
                    "name": "muted"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              }
            },
            {
              "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.Speaker interface directives to your add-on.

SetVolume directive

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

SetVolume directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.Speaker",
      "name": "SetVolume",
      "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": {
      "volume": 50
    }
  }
}

SetVolume directive payload

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

Property	Description	Type
`volume`	The volume to set the device to.	Integer

SetVolume response

If you handle a SetVolume directive successfully, respond with an Alexa.Response event. A successful response confirms that the endpoint completed the requested action. In the context object, include the values of all properties that changed. The following example shows a SetVolume 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.Speaker",
        "name": "volume",
        "value": 50,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.Speaker",
        "name": "muted",
        "value": false,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:18:40.12Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

SetVolume directive error handling

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

AdjustVolume directive

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

AdjustVolume directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.Speaker",
      "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": {
      "volume": -20,
      "volumeDefault": false
    }
  }
}

AdjustVolume directive payload

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

Property	Description	Type
`volume`	The amount by which to change the volume, relative to the current volume.	Integer
`volumeDefault`	False if the user specified the amount by which to change the volume; otherwise true.	Boolean

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. In the context object, include the values of all properties that changed. 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.Speaker",
        "name": "volume",
        "value": 30,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.Speaker",
        "name": "muted",
        "value": false,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:18:40.12Z",
        "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:

SetMute directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.Speaker",
      "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`	Set to `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. In the context object, include the values of all properties that changed. 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.Speaker",
        "name": "volume",
        "value": 30,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.Speaker",
        "name": "muted",
        "value": true,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:18:40.12Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

SetMute directive error handling

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

State reporting

Alexa sends a ReportState directive to request information about the state of an endpoint. When Alexa sends a ReportState directive, you send a StateReport event in response. The response contains the current state of all the retrievable properties in the context object. You identify your retrievable properties in your discovery response. For details about state reports, see Understand State and Change Reporting.

StateReport response example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.Speaker",
        "name": "volume",
        "value": 30,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.Speaker",
        "name": "muted",
        "value": false,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:18:40.12Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

Change reporting

You send a ChangeReport event to report changes proactively in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.

ChangeReport event example

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "VOICE_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.Speaker",
            "name": "volume",
            "value": 40,
            "timeOfSample": "2017-02-03T16:52:50.52Z",
            "uncertaintyInMilliseconds": 0
          },
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.Speaker",
        "name": "muted",
        "value": false,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:18:40.12Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Utterances

Reportable properties

Volume property

Muted property

Discovery

Discover response example

Directives

SetVolume directive

SetVolume directive example

SetVolume directive payload

SetVolume response

SetVolume directive error handling

AdjustVolume directive

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

State reporting

StateReport response example

Change reporting

ChangeReport event example

​Utterances

​Reportable properties

​Volume property

​Muted property

​Discovery

​Discover response example

​Directives

​SetVolume directive

​SetVolume directive example

​SetVolume directive payload

​SetVolume response

​SetVolume directive error handling

​AdjustVolume directive

​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

​State reporting

​StateReport response example

​Change reporting

​ChangeReport event example

​Related topics

Utterances

Reportable properties

Volume property

Muted property

Discovery

Discover response example

Directives

SetVolume directive

SetVolume directive example

SetVolume directive payload

SetVolume response

SetVolume directive error handling

AdjustVolume directive

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

State reporting

StateReport response example

Change reporting

ChangeReport event example

Related topics