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 the GetSnapshot 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

isAvailable

Specifies whether the snapshot feature is available on the endpoint. Alexa only sends the getSnapshot directive when this value is true.

Boolean

Yes

unavailabilityReason

Specifies the reason that the snapshot feature is unavailable. Include when you set isAvailable to false.
Valid values: SUBSCRIPTION_REQUIRED, DISABLED_BY_USER.

String

No

minRefreshIntervalInSeconds

Minimum time interval in seconds between requests for a new snapshot.
Alexa uses this value as one criteria to send the getSnapshot directive. Set to the value that the customer set in your camera app or the fixed refresh rate defined in your skill.

Long

No

Discover response example

The following example shows an Alexa.Discover.Response message for a device that supports the Alexa.SmartVision.SnapshotProvider interface.

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": "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.

Copied to clipboard.

{
    "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

preferOnDemandSnapshot

Indicates that the camera should return a new snapshot, if supported. Otherwise, the camera can return a cached snapshot, if available.
When set to true, Alexa ignores the minRefreshIntervalInSeconds configuration.
Default: false.

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

value

Defines the link to the snapshot image.

Object

Yes

value.uri

Specifies the URI for the snapshot stored for the endpoint.
For more details, see Snapshot image guidelines.

String

Yes

value.uriExpirationTime

Expiration of the URI.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

Yes

value.authenticationType

Type of authentication required to access the URI.
For more details, see Snapshot image guidelines.
Valid value: ACCESS_TOKEN.

String

Yes

timeOfSample

Timestamp on the snapshot that indicates the time the snapshot was taken.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

Yes

uncertaintyInMilliseconds

Uncertainty of the timeOfSample field in milliseconds.
For example, uncertainty due to the transmission delay between the action in front of the camera and the corresponding image processing software.

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.

Was this page helpful?

Last updated: Aug 23, 2024