Alexa.DataStore Interface Reference

The Alexa.DataStore interface provides requests that notify your skill about errors that might occur when you update the data store on a device. The data store is an area installed locally to a device that contains data an Alexa Presentation Language (APL) document can access with data binding. Widgets use the data store to display content without sending requests to your skill and waiting on a response.

For details about widgets, see About Widgets and Alexa Presentation Language (APL).

Enable the Alexa.DataStore interface

To use the Alexa.DataStore interface, you must enable it in your skill. You can use either the developer console or the ASK CLI to update your skill to support this interface.

Configure the interface in the developer console

  1. Sign in to the developer console, and click the name of the skill you want to configure.
  2. Navigate to the Build > Interfaces page.

  3. Enable the Data Store option.

    This action automatically enables Data Store under Alexa Extensions.

  4. Click Save Interfaces and then Build Model to re-build your interaction model.

Configure the interface with the ASK CLI

Add ALEXA_DATA_STORE to your skill manifest in the manifest.apis.custom.interfaces array, as shown in the following example.

{
  "manifest": {
    "apis": {
      "custom": {
        "endpoint": {},
        "interfaces": [
          {
            "type": "ALEXA_DATA_STORE"
          }
        ],
        "regions": {}
      }
    },
    "manifestVersion": "1.0",
    "privacyAndCompliance": {},
    "publishingInformation": {}
  }
}

Requests

DataStoreError request

Sent to notify the skill when a data store update failed due to an error. The request includes details you can use to attempt the update again.

For example, you might use the Data Store REST API to send an update to device that's offline and therefore unreachable. In this scenario, Alexa retries your update when the device comes back online. If the delivery expiry period that you specify as part of the REST operation expires and the device is still offline, your skill receives the DataStoreError request so that you can either handle the error or try to send the payload again.

The DataStoreError has the properties shown in the following table.

Property Type Required Description

type

String

Yes

Set to Alexa.DataStore.DataStoreError.

error

Error object

Yes

Error object that contains details about the error that occurred.

error.type

Enumeration

Yes

Type of error.
Possible values:

  • STORAGE_LIMIT_EXCEEDED
  • DATASTORE_INTERNAL_ERROR
  • DEVICE_UNAVAILABLE
  • DEVICE_PERMANENTLY_UNAVAILABLE

DEVICE_UNAVAILABLE and DEVICE_PERMANENTLY_UNAVAILABLE errors

Property Type Required Description

type

Enumeration

Yes

Subtype of the error.
Possible values:

  • DEVICE_UNAVAILABLE – Sent when the device has remained offline after attemptDeliveryUntil.
  • DEVICE_PERMANENTLY_UNAVAILABLE – The device registration has changed. Therefore, the skill must stop pushing data to this device or INVALID_TARGET is reported.

content

Object

Yes

Object containing the content of the error.

content.deviceId

String

Yes

Device ID for the device that is unreachable.

content.commands

Array of commands

Yes

Consolidated commands that had been sent to the unreachable device, ordered by the original request time.

The following example shows a DEVICE_UNAVAILABLE error.

{
  "type": "Alexa.DataStore.Error",
  "error": {
    "type": "DEVICE_UNAVAILABLE",
    "content": {
      "deviceId": "device-id",
      "commands": [
        {
          "type": "PUT_OBJECT",
          "namespace": "namespace-for-the-command",
          "key": "key-from-the-command",
          "content": {}
        }
      ]
    }
  }
}

Storage limit and data store internal errors

Property Type Required Description

type

Enumeration

Yes

Subtype of the error.
Possible values:

  • STORAGE_LIMIT_EXCEEDED
  • DATASTORE_INTERNAL_ERROR

content

Object

Yes

Object containing the content of the error.

content.deviceId

String

Yes

Device account ID where the error occurred.

content.failedCommand

Command

Yes

The command that failed due to the error

content.message

String

No

Message describing the error.

The following example shows a STORAGE_LIMIT_EXCEEDED error.

{
  "type": "Alexa.DataStore.Error",
  "error": {
    "type": "STORAGE_LIMIT_EXCEEDED",
    "content": {
      "deviceId": "device-id",
      "failedCommand": {
        "type": "PUT_OBJECT",
        "namespace": "namespace-from-the-command",
        "key": "key-from-the-command",
        "content": {}
      }
    }
  }
}
Was this page helpful?

Last updated: Nov 28, 2023