Alexa.DataController Interface 1.0

Implement the Alexa.DataController interface in your Alexa add-on 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 add-on receives a data controller directive. When the customer deletes data directly on the device or device app, your add-on 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 add-on. After your add-on 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 add-on. 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. Order of directives and events for a data request that has three DataReport results.

Order of directives and events for a data request that has three DataReport results.

Utterances

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

Properties and objects

The Alexa.DataController interface defines the following properties and objects.

Reportable properties

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

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`	List of unique IDs used for query by ID. Maximum: 10 IDs.	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. For the full list of display categories, see display categories. An endpoint can support multiple data controllers, so you must always include the instance name in your events and responses. Include an Alexa.DataController instance for each interface and schema that the same endpoint supports. Define an instance name that describes the data. To let Alexa know the health of your device, also implement the Alexa.EndpointHealth interface.

Configuration object

In addition to the usual discovery response fields, for Alexa.DataController, 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 and Alexa.SmartVision.ObjectDetectionSensor interfaces.

{
    "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": "1.0",
                        "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",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Directives and events

The Alexa.DataController interface defines the following 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 add-on to retrieve data by ID. 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 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 add-on to delete data by time range.

{
    "directive": {
        "header": {
            "namespace": "Alexa.DataController",
            "name": "DeleteData",
            "payloadVersion": "1.0",
            "instance": "DataController-SmartVisionData",
            "messageId": "Unique 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:50Z"
            }
        }
    }
}

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 add-on. In response, your add-on 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 add-on sends to Alexa in response to a ReportData directive. The example includes the correlationToken.

{
    "event": {
        "header": {
            "namespace": "Alexa.DataController",
            "name": "DataReport",
            "instance": "DataController-SmartVisionData",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token that matches the request",
            "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 add-on proactively sent a DataReport event and Alexa handles the event successfully, your add-on 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 add-on is disabled.
`404 Not Found`	Indicates that the add-on 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 IDs 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 add-on can retry by using exponential back-off.
`503 Service Unavailable`	Server is busy or unavailable. The add-on 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 ID. 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 add-on 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.

{
    "event": {
        "header": {
            "namespace": "Alexa.DataController",
            "name": "DataDeleted",
            "instance": "DataController-SmartVisionData",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token that matches the request",
            "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 add-on proactively sent a DataDeleted event and Alexa handles the event successfully, your add-on receives HTTP status code 202 Success. On error, Alexa sends the appropriate HTTP status code. If Alexa sent the DataDeleted event to your add-on 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 add-on is disabled.
`404 Not Found`	Indicates that the add-on 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 IDs 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 add-on can retry by using exponential back-off.
`503 Service Unavailable`	Server is busy or unavailable. The add-on 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.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Data retrieval

Utterances

Properties and objects

Reportable properties

DataRetrievalSchema object

Query object

Discovery

Configuration object

Discover response example

Directives and events

ReportData directive

ReportData directive example

ReportData directive payload

ReportData response

ReportData directive error handling

DeleteData directive

DeleteData directive example

DeleteData directive payload

DeleteData response

DeleteData directive error handling

DataReport event

DataReport event example

DataReport event payload

DataReport response

DataDeleted event

DataDeleted event example

DataDeleted event payload

DataDeleted response

Change reporting

​Data retrieval

​Utterances

​Properties and objects

​Reportable properties

​DataRetrievalSchema object

​Query object

​Discovery

​Configuration object

​Discover response example

​Directives and events

​ReportData directive

​ReportData directive example

​ReportData directive payload

​ReportData response

​ReportData directive error handling

​DeleteData directive

​DeleteData directive example

​DeleteData directive payload

​DeleteData response

​DeleteData directive error handling

​DataReport event

​DataReport event example

​DataReport event payload

​DataReport response

​DataDeleted event

​DataDeleted event example

​DataDeleted event payload

​DataDeleted response

​Change reporting

​Related topics

Data retrieval

Utterances

Properties and objects

Reportable properties

DataRetrievalSchema object

Query object

Discovery

Configuration object

Discover response example

Directives and events

ReportData directive

ReportData directive example

ReportData directive payload

ReportData response

ReportData directive error handling

DeleteData directive

DeleteData directive example

DeleteData directive payload

DeleteData response

DeleteData directive error handling

DataReport event

DataReport event example

DataReport event payload

DataReport response

DataDeleted event

DataDeleted event example

DataDeleted event payload

DataDeleted response

Change reporting

Related topics