Alexa.DataController Interface 1.0
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.
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 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 |
|---|---|---|
|
|
Data format. |
String |
|
|
Name of the data schema. |
String |
Query object
The Query object defines the query string for the ReportData and DeleteData directives. All properties are optional.
| Property | Description | Type |
|---|---|---|
|
|
Unique identifiers for query by identifier. |
Array of string |
|
|
Beginning time for query by timestamp range. |
|
|
|
End time for query by timestamp range. |
|
Discovery
You describe endpoints that support Alexa.DataController by using the standard discovery mechanism described in Alexa.Discovery.
Alexa.DataController interface doesn't have any controllable properties.To let Alexa know the health of your device, also implement the Alexa.EndpointHealth interface.
Capabilities object
An endpoint can support multiple data controllers, so you must always include the instance name in your events and responses. Define an instance for each interface and schema that the same endpoint supports in the capabilities object.
The following example shows a data controller instance.
{
"type": "AlexaInterface",
"interface": "Alexa.DataController",
"instance": "DataController-SmartVisionData",
"version": "1.0"
}
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 |
|---|---|---|---|
|
|
Alexa interface that this controller applies to. |
String |
Yes |
|
|
Version of the Alexa interface that this controller applies to. |
String |
Yes |
|
|
Indicates that the |
|
No |
|
|
Indicates the search methods supported for data access. |
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 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 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 |
|---|---|---|---|
|
|
Identifies how to search the data. |
String |
Yes |
|
|
Identifies the search string based on the specified |
Query object |
No |
|
|
Specifies the maximum number of matching results to return. |
Integer |
Yes |
|
|
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 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 |
|---|---|---|---|
|
|
Identifies how to search the data. |
String |
Yes |
|
|
Identifies the search string based on the specified |
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.
{
"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 |
|---|---|---|---|
|
|
Information about the next page of results. If you don't support pagination, don't include this parameter. |
Object |
No |
|
|
Token used to report the next page of results. If there are more results, include this parameter. |
String |
No |
|
|
Schema of the included data. You identified the schema format in your discovery response. |
DataRetrievalSchema object |
No |
|
|
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 |
|---|---|
|
|
Operation succeeded. |
|
|
Indicates that the request is invalid or badly formatted. Verify the event payload and check for any missing or invalid fields. For example, the |
|
|
Indicates that the request didn't include the authorization token or the token is invalid or expired. |
|
|
Indicates that the authorization token doesn't have sufficient permissions or the skill is disabled. |
|
|
Indicates that the skill doesn't exist in the corresponding stage. |
|
|
Maximum number or size of a parameter exceeds the limit. For example, more than 50 identifiers are included in the |
|
|
Number of requests per minute is too high. Use exponential back-off and retry the request. |
|
|
An error occurred on the server. The skill can retry by using exponential back-off. |
|
|
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.
{
"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 |
|---|---|---|---|
|
|
Identifies how to search the data. |
String |
Yes |
|
|
Identifies the search string based on the specified |
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 |
|---|---|
|
|
Operation succeeded. |
|
|
Indicates that the request is invalid or badly formatted. Verify the event payload and check for any missing or invalid fields. For example, the |
|
|
Indicates that the request didn't include the authorization token or the token is invalid or expired. |
|
|
Indicates that the authorization token doesn't have sufficient permissions or the skill is disabled. |
|
|
Indicates that the skill doesn't exist in the corresponding stage. |
|
|
Maximum number or size of a parameter exceeds the limit. For example, more than 50 identifiers are included in the |
|
|
Number of requests per minute is too high. Use exponential back-off and retry the request. |
|
|
An error occurred on the server. The skill can retry by using exponential back-off. |
|
|
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.
Alexa.DataController interface doesn't define any proactively reportable properties. However, you send change reports for the other interfaces that you implement in your skill. Related topics
- Alexa.ModeController
- Alexa.RangeController
- Alexa.SimpleEventSource
- Alexa.ToggleController
- Works with Alexa certification
Last updated: Nov 22, 2023