Alexa.SmartVision.SnapshotProvider Interface 1.1
Implement the Alexa.SmartVision.SnapshotProvider
interface in your Alexa skill so that users can request Alexa to retrieve and display snapshot images from their security cameras and other camera devices.
For the list of languages that the Alexa.SmartVision.SnapshotProvider
interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.
Snapshot image guidelines
You send the image to Alexa as a URI. When the customer displays their camera device in the Alexa app, Alexa downloads and displays the snapshot image.
The snapshot image must meet the following guidelines:
- The image must be one of the supported media types: JPEG or PNG.
- Minimum image resolution: 360 pixels.
- Set an expiration time for the URI. Amazon recommends that the URI remain valid for 10 minutes.
- Alexa downloads the image by sending an
HTTP GET
request to the URI with the following header fields:Accept: image/jpeg, image/png Authorization: Bearer {access token}
- Alexa doesn't support URI redirects from the provided URI.
- The URI should return the image media type in the
Content-type
header field set to one of the following types:image/jpeg
image/png
(Default, if you don't include the media type.)
- The URI should not be publicly accessible. Access to the URI should require authentication. Alexa supports access token authentication and sends the access token as part of the
Authorization
header field in the URI download. In response, your service should do the following checks:- Verify that the access token exists.
- Verify that the token represents a valid user in your resource server.
- Verify that the given user has the correct access privileges for the given snapshot.
- If the URI becomes invalid or expires, return
HTTP Status 410
. On receipt of the error, Alexa will retry theGetSnapshot
directive to fetch a new URI.
Utterances
The Alexa.SmartVision.SnapshotProvider
interface doesn't define any user utterances.
Reportable properties
The Alexa.SmartVision.SnapshotProvider
interface doesn't define any reportable properties.
Discovery
You describe endpoints that support the Alexa.SmartVision.SnapshotProvider
interface by using the standard discovery mechanism described in Alexa.Discovery
. Use CAMERA
for the display category. For the full list of display categories, see display categories.
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, include a configuration
object that contains the following fields.
Property | Description | Type | Required |
---|---|---|---|
|
Specifies whether the snapshot feature is available on the endpoint. Alexa only sends the |
Boolean |
Yes |
|
Specifies the reason that the snapshot feature is unavailable. Include when you set |
String |
No |
|
Minimum time interval in seconds between requests for a new snapshot. |
Long |
No |
Discover response example
The following example shows an Alexa.Discover.Response
message for a device that supports the Alexa.SmartVision.SnapshotProvider
interface.
{
"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": "Manufacturer name of the endpoint",
"description": "Description to be shown in the Alexa app",
"friendlyName": "Your device name, displayed in the Alexa app",
"displayCategories": ["CAMERA"],
"additionalAttributes": {
"manufacturer": "Manufacturer name of the endpoint",
"model": "Model of the device",
"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"
},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.SmartVision.SnapshotProvider",
"version": "1.1",
"configuration": {
"isAvailable": false,
"unavailabilityReason": "SUBSCRIPTION_REQUIRED",
"minRefreshIntervalInSeconds": 180
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.1",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}]
}
}
}
AddOrUpdateReport
If the feature support of your endpoint changes, you must proactively send an Alexa.Discovery.AddOrUpdateReport
event. For example, if the snapshot availability changes due to a change in the subscription status. For details, see AddOrUpdateReport event.
AddOrUpdateReport event example
The following example shows an AddOrUpdateReport
message to report the feature is available.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"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.SmartVision.SnapshotProvider",
"version": "1.1",
"configuration": {
"isAvailable": true,
"minRefreshIntervalInSeconds": 180
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.1",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}]
}
}
}
Directives
The Alexa.SmartVision.SnapshotProvider
interface defines the following directives.
GetSnapshot
Support the GetSnapshot
directive so that users can request a snapshot from the endpoint.
GetSnapshot directive example
The following example shows a request to retrieve a snapshot URI.
{
"directive": {
"header": {
"namespace": "Alexa.SmartVision.SnapshotProvider",
"name": "GetSnapshot",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "1.1"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "an OAuth2 bearer token"
},
"endpointId": "Endpoint ID",
"cookie": {}
},
"payload": {
"preferOnDemandSnapshot": true
}
}
}
GetSnapshot directive payload
The following table shows the payload details for the GetSnapshot
directive.
Property | Description | Type | Required |
---|---|---|---|
|
Indicates that the camera should return a new snapshot, if supported. Otherwise, the camera can return a cached snapshot, if available. |
Boolean |
No |
GetSnapshot response
If you handle a GetSnapshot
directive successfully, respond with a Snapshot
event. Include the URI to the snapshot image in the response.
If you send a cached image, or your device can take a snapshot within eight seconds, send a synchronous response. If your device takes longer than eight seconds, first send a DeferredResponse, and then send an asynchronous Snapshot
event when the snapshot is available. Include a correlation token in your responses. If you respond asynchronously, also include a scope
with an authorization token in the response.
The following example shows a synchronous Snapshot
response.
The following example shows a DeferredResponse
response, followed by an asynchronous Snapshot
response.
The following table shows the payload details for the Snapshot
event.
Property | Description | Type | Required |
---|---|---|---|
|
Defines the link to the snapshot image. |
Object |
Yes |
|
Specifies the URI for the snapshot stored for the endpoint. |
String |
Yes |
|
Expiration of the URI. |
String |
Yes |
|
Type of authentication required to access the URI. |
String |
Yes |
|
Timestamp on the snapshot that indicates the time the snapshot was taken. |
String |
Yes |
|
Uncertainty of the |
Number |
Yes |
GetSnapshot error handling
If you can't handle a GetSnapshot
directive successfully, respond with an Alexa.SmartVision.SnapshotProvider.ErrorResponse
. You can also respond with a generic Alexa.ErrorResponse
event if your error isn't specific to the snapshot capability.
Related topics
Last updated: Aug 23, 2024