Your Alexa Dashboards Settings

Alexa.PercentageController Interface

The PercentageController interface describes the messages used to control properties of endpoints that can be expressed as a percentage. Use this interface only if there is not a more specific controller interface that applies to your device. In general, you should implement the most specific interface possible.

For example, if you want to handle request specific to brightness values, use Alexa.BrightnessController. If you want to handle requests specific to the power level of an endpoint such as a dimmer switch, see Alexa.PowerLevelController.

Directives

The control and query directives in this interface are supported in skills that target the following languages:

  • English - all locales
  • German
  • Japanese

See Develop Smart Home Skills in Multiple Languages for more information.

SetPercentage

Request to set the percentage value for an endpoint.

“Alexa, set name to number percent”

“Alexa, stelle Geräteame auf Anzahl Prozent”

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.PercentageController",
      "name": "SetPercentage",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "percentage": 74
    }
  }
}
Field Description Type Required
percentage The percentage value to set for the device. Integer from 0-100, inclusive. Yes

AdjustPercentage

Request to increase or decrease the percentage value of a device setting.

“Alexa, increase device name by number percent”

“Alexa, decrease device name by number percent”

“Alexa, erhöhe Gerätename um Anzahl Prozent”

“Alexa, reduziere Gerätename um Anzahl Prozent”

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.PercentageController",
      "name": "AdjustPercentage",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "percentageDelta": -20
    }
  }
}

Field Description Type Required
percentageDelta The desired change in percentage. A positive or negative integer value used to increase or decrease the percentage. For example, a starting value of 100 and a percentage delta of -3 would result in a final value of 97. Integer from -100 to 100, inclusive. Yes

Properties and Events

For this interface, you must either reply:

  • Synchronously, which means you send a Response event to Alexa from the Lambda function.
  • Asynchronously, which means you send a Response event to the Alexa event gateway. When you reply asynchronously, you must include a scope with an authorization token to identify the customer, and a correlation token to identify the directive you are responding to.

When you send a Response, you should include the state of reportable properties in the context of the message.

Reportable Properties

Property Name Type Description
percentage Percentage The percentage value of an appliance setting. This could be the brightness, speed, power level or other values. The value is an integer ranging from 0 to 100, inclusive.

Response

If a percentage directive was successfully handled, you should respond with an Response event.

Example Response

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.PercentageController",
      "name": "percentage",
      "value": 74,
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 1000
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason. See Error.Response for more details.

Additional Sample Code

See the sample request and response messages in the Alexa smart home GitHub repo:

PercentageController

Interface Description
Alexa.BrightnessController Sets brightness for a light as a percentage.