Alexa.DataController Interface

Implement the Alexa.DataController interface in your Alexa skill to enable users to view and delete data on Alexa, on the device, and in the device cloud. When the customer asks Alexa to view or delete data, your skill receives a data controller directive. When the customer deletes data directly on the device or device app, your skill sends the data controller events to Alexa. The Alexa.DataController interface is a generic controller interface.

Typically, you use the Alexa.DataController interface with the Alexa.SmartVision.ObjectDetectionSensor interface.

For the list of languages that the Alexa.DataController interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Data retrieval

Alexa initiates data retrieval by sending a directive to your skill. After your skill reports the requested data, Alexa might display the data to the customer in the Alexa app. Also, you can report the data proactively by sending an event to Alexa.

The following example shows the message flow when Alexa requests data from your skill. The nextToken parameter in the DataReport event indicates that there are multiple results. To get the next results, Alexa sends another ReportData directive with a matching nextToken.

Diagram showing order of directives and events for a data request that has three results.

Utterances

The Alexa.DataController interface doesn't have any user utterances. Instead, Alexa communicates with your skill after the customer requests to view and delete data from the Alexa app.

Properties and objects

The Alexa.DataController interface doesn't include any reportable properties.

An endpoint can support multiple data controllers, so you must always include the instance name in your events and responses. You identify your instance names in your discovery response.

DataRetrievalSchema object

The DataRetrievalSchema object defines the data format and name of the schema for the data published in the DataReport event.

Property Description Type

type

Data format.
Valid values: BINARY, JSON.

String

schema

Name of the data schema.
For JSON schemas, set to the JSON type defined by the data controller instance. For binary schemas, set to the published schema.

String

Query object

The Query object defines the query string for the ReportData and DeleteData directives. All properties are optional.

Property Description Type

ids

Unique identifiers for query by identifier.
Maximum: 10 identifiers.

Array of string

fromTime

Beginning time for query by timestamp range.
If not specified, the query starts from the time of the earliest data item available.

DateTime object

toTime

End time for query by timestamp range.
If not specified, the query ends at the time of the latest data item available.

DateTime object

Discovery

You describe endpoints that support Alexa.DataController by using the standard discovery mechanism described in Alexa.Discovery.

In addition to the usual discovery response fields, for Alexa.DataController, include an instance name that describes the data. Define an instance for each interface and schema that the same endpoint supports. Also include a configuration object that contains the following fields.

Property Description Type Required

targetCapability.name

Alexa interface that this controller applies to.

String

Yes

targetCapability.version

Version of the Alexa interface that this controller applies to.

String

Yes

dataRetrievalSchema

Indicates that the targetCapability supports data retrieval. If not present, the capability doesn't support data retrieval.

DataRetrievalSchema object

No

supportedAccess

Indicates the search methods supported for data access.
Valid values: BY_IDENTIFIER, BY_TIMESTAMP_RANGE.

Array of strings

Yes

Discover response example

The following example shows a Discover.Response message for a smart-vision camera that supports the Alexa.DataController, Alexa.SmartVision.ObjectDetectionSensor, and Alexa.EndpointHealth interfaces.

Copied to clipboard.

{
    "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": "Sample Manufacturer",
                "description": "Description that appears in the Alexa app",
                "friendlyName": "Your device name, displayed in the Alexa app",
                "displayCategories": ["CAMERA"],
                "additionalAttributes": {
                    "manufacturer": "Sample Manufacturer",
                    "model": "Sample Model",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.DataController",
                        "instance": "DataController-SmartVisionData",
                        "version": "3",
                        "properties": {},
                        "configuration": {
                            "targetCapability": {
                                "name": "Alexa.SmartVision.ObjectDetectionSensor",
                                "version": "1.0"
                            },
                            "dataRetrievalSchema": {
                                "type": "JSON",
                                "schema": "SmartVisionData"
                            },
                            "supportedAccess": ["BY_IDENTIFIER", "BY_TIMESTAMP_RANGE"]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.SmartVision.ObjectDetectionSensor",
                        "version": "1.0",
                        "properties": {
                            "supported": [{
                                "name": "objectDetectionClasses"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "objectDetectionConfiguration": [{
                                    "imageNetClass": "person"
                                },
                                {
                                    "imageNetClass": "package",
                                    "isAvailable": false,
                                    "unavailabilityReason": "SUBSCRIPTION_REQUIRED"
                                }
                            ]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Directives and events

ReportData directive

Support the ReportData directive so that a customer can request to view data stored on your endpoint.

ReportData directive example

The following example shows a ReportData directive that Alexa sends to a smart-vision camera skill to retrieve data by identifier. The directive doesn't include the token because Alexa requests the first page of data.

{
    "directive": {
        "header": {
            "namespace": "Alexa.DataController",
            "name": "ReportData",
            "payloadVersion": "1.0",
            "instance": "DataController-SmartVisionData",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2 bearer token"
            },
            "endpointId": "endpoint id",
            "cookie": {}
        },
        "payload": {
            "queryType": "QUERY_BY_IDENTIFIER",
            "query": {
                "ids": ["unique data identifier"]
            },
            "maxResults": 1
        }
    }
}

ReportData directive payload

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

Property Description Type Required

queryType

Identifies how to search the data.
Valid values: QUERY_BY_IDENTIFIER, QUERY_BY_TIMESTAMP_RANGE, QUERY_ALL.

String

Yes

query

Identifies the search string based on the specified queryType. Include for QUERY_BY_IDENTIFIER and QUERY_BY_TIMESTAMP_RANGE.

Query object

No

maxResults

Specifies the maximum number of matching results to return.
Valid values: 1 – 10, inclusive.

Integer

Yes

nextToken

Token to use to retrieve a specific page of the results. If the token isn't included, the response contains the first page of the matching results.

String

No

ReportData response

If you handle a ReportData directive successfully, respond with a DataReport event. Include the data in the response.

ReportData directive error handling

If you can't handle a ReportData directive successfully, respond with an Alexa.DataController.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event.

DeleteData directive

Support the DeleteData directive so that a customer can request to delete data from your endpoint.

DeleteData directive example

The following example shows a DeleteData directive that Alexa sends to a smart-vision camera skill to delete data by time range.

{
    "directive": {
        "header": {
            "namespace": "Alexa.DataController",
            "name": "DeleteData",
            "payloadVersion": "1.0",
            "instance": "DataController-SmartVisionData",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2 bearer token"
            },
            "endpointId": "endpoint id",
            "cookie": {}
        },
        "payload": {
            "queryType": "QUERY_BY_TIMESTAMP_RANGE",
            "query": {
                "fromTime": "2021-12-12T10:30:00:00Z",
                "toTime": "2021-12-12T16:20:50:52Z"
            }
        }
    }
}

DeleteData directive payload

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

Property Description Type Required

queryType

Identifies how to search the data.
Valid values: QUERY_BY_IDENTIFIER, QUERY_BY_TIMESTAMP_RANGE, QUERY_ALL.

String

Yes

query

Identifies the search string based on the specified queryType. Include for QUERY_BY_IDENTIFIER and QUERY_BY_TIMESTAMP_RANGE.

Query object

No

DeleteData response

If you handle a DeleteData directive successfully, respond with an DataDeleted event.

DeleteData directive error handling

If you can't handle a DeleteData directive successfully, respond with an Alexa.DataController.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event.

DataReport event

Send a DataReport event to the Alexa event gateway to report data proactively to Alexa. For details, see Send Events to the Event Gateway. You can send the event at any time or in response to a ReportData directive. Include the correlation token if you send the event in response to the directive. Otherwise, don't include the correlation token.

The event includes a token that indicates whether there is more data to retrieve. After Alexa receives a DataReport event that includes a nextToken parameter, Alexa sends a ReportData directive with the same nextToken value to your skill. In response, your skill must send the next set of data results in another DataReport event.

DataReport event example

The following example shows a DataReport event that a smart-vision camera skill sends to Alexa in response to a ReportData directive. The example includes the correlationToken.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.DataController",
            "name": "DataReport",
            "instance": "DataController-SmartVisionData",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token",
            "payloadVersion": "1.0"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "Opaque correlation token"
            },
            "endpointId": "endpoint id"
        },
        "payload": {
            "paginationContext": {
                "nextToken": "token1"
            },
            "dataSchema": {
                "type": "JSON",
                "schema": "SmartVisionData"
            },
            "data": [{
                    "eventIdentifier": "2b3409df-d686-4a52-9bba-d361860bac61",
                    "imageNetClass": "person",
                    "mediaId": "2c3409df-d686-4a52-9bba-d361860bac61",
                    "objectIdentifier": "4a3409df-d686-4a52-9bba-d361860bacbf",
                    "frameIndex": 2,
                    "frameWidthInPixels": 1980,
                    "frameHeightInPixels": 1080,
                    "frameImageUri": "https://example.com/frames/frame1.jpg",
                    "croppedImageUri": "https://example.com/images/image1.jpg"
                },
                {
                    "eventIdentifier": "2b3409df-d686-4a52-9bba-d361860bac62",
                    "imageNetClass": "package",
                    "mediaId": "2c3409df-d686-4a52-9bba-d361860bac62",
                    "objectIdentifier": "4a3409df-d686-4a52-9bba-d361860b4562",
                    "frameIndex": 5,
                    "frameWidthInPixels": 1980,
                    "frameHeightInPixels": 1080,
                    "frameImageUri": "https://example.com/frames/frame2.jpg",
                    "croppedImageUri": "https://example.com/images/image2.jpg"
                }
            ]
        }
    }
}

DataReport event payload

The following table shows the payload details for the DataReport event.

Property Description Type Required

paginationContext

Information about the next page of results. If you don't support pagination, don't include this parameter.

Object

No

paginationContext.nextToken

Token used to report the next page of results. If there are more results, include this parameter.

String

No

dataSchema

Schema of the included data. You identified the schema format in your discovery response.

DataRetrievalSchema object

No

data

For JSON schemas, include the array of JSON data. For binary schemas, don't include this parameter and pass the data as a multi-part attachment.

Array of String

No

DataReport response

If your skill proactively sent a DataReport event and Alexa handles the event successfully, your skill receives HTTP status code 202 Success. On error, Alexa sends the appropriate HTTP status code.

The following table shows the HTTP status codes sent in response to the event.

Status Description

202 Success

Operation succeeded.

400 Invalid Request

Indicates that the request is invalid or badly formatted. Verify the event payload and check for any missing or invalid fields. For example, the data format must match the specified dataSchema.

401 Unauthorized

Indicates that the request didn't include the authorization token or the token is invalid or expired.

403 Forbidden

Indicates that the authorization token doesn't have sufficient permissions or the skill is disabled.

404 Not Found

Indicates that the skill doesn't exist in the corresponding stage.

413 Request Entity Too Large

Maximum number or size of a parameter exceeds the limit. For example, more than 50 identifiers are included in the DataDeleted event.

429 Too Many Requests response

Number of requests per minute is too high. Use exponential back-off and retry the request.

500 Internal Server Error

An error occurred on the server. The skill can retry by using exponential back-off.

503 Service Unavailable

Server is busy or unavailable. The skill can retry by using exponential back-off.

DataDeleted event

Send a DataDeleted event to the Alexa event gateway to notify Alexa proactively that you deleted the data identified by a unique identifier. For details, see Send Events to the Event Gateway. You can send the event at any time or in response to a DeleteData directive. Include the correlation token if you send the event in response to the directive. Otherwise, don't include the correlation token.

DataDeleted event example

The following example shows a DataDeleted event that a smart-vision camera skill sends to Alexa in response to a DeleteData directive. Include the correlation token if you send the event in response to the directive. Otherwise, don't include the correlation token.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.DataController",
            "name": "DataDeleted",
            "instance": "DataController-SmartVisionData",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token",
            "payloadVersion": "1.0"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "Opaque correlation token"
            },
            "endpointId": "endpoint id"
        },
        "payload": {
            "queryType": "QUERY_BY_IDENTIFIER",
            "query": {
                "ids": ["2b3409df-d686-4a52-9bba-d361860bac61", "2b3409df-d686-4a52-9bba-d361860bac62"]
            }
        }
    }
}

DataDeleted event payload

The following table shows the payload details for the DataDeleted event.

Property Description Type Required

queryType

Identifies how to search the data.
Valid values: QUERY_BY_IDENTIFIER, QUERY_BY_TIMESTAMP_RANGE, QUERY_ALL.

String

Yes

query

Identifies the search string based on the specified queryType. Include for QUERY_BY_IDENTIFIER and QUERY_BY_TIMESTAMP_RANGE.

Query object

No

DataDeleted response

If your skill proactively sent a DataDeleted event and Alexa handles the event successfully, your skill receives HTTP status code 202 Success. On error, Alexa sends the appropriate HTTP status code. If Alexa sent the DataDeleted event to your skill proactively, respond with the appropriate HTTP status code.

The following table shows the HTTP status codes sent in response to the event.

Status Description

202 Success

Operation succeeded.

400 Invalid Request

Indicates that the request is invalid or badly formatted. Verify the event payload and check for any missing or invalid fields. For example, the data format must match the specified dataSchema.

401 Unauthorized

Indicates that the request didn't include the authorization token or the token is invalid or expired.

403 Forbidden

Indicates that the authorization token doesn't have sufficient permissions or the skill is disabled.

404 Not Found

Indicates that the skill doesn't exist in the corresponding stage.

413 Request Entity Too Large

Maximum number or size of a parameter exceeds the limit. For example, more than 50 identifiers are included in the DataDeleted event.

429 Too Many Requests response

Number of requests per minute is too high. Use exponential back-off and retry the request.

500 Internal Server Error

An error occurred on the server. The skill can retry by using exponential back-off.

503 Service Unavailable

Server is busy or unavailable. The skill can retry by using exponential back-off.

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.