Alexa.SmartVision.SnapshotProvider Interface 1.1

Implement the Alexa.SmartVision.SnapshotProvider interface in your Alexa add-on 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

In response to a GetSnapshot directive from Alexa, you send a URI to the snapshot image. When the customer opens their camera device in the Alexa app, Alexa downloads and displays the snapshot image. For doorbells with a camera, snapshot freshness is event-driven, triggered by a motion detection or doorbell ring. In response to a GetSnapshot directive, send the most recent snapshot captured during a wake event. The preferOnDemandSnapshot property isn’t supported for doorbell devices. The image must meet the following guidelines for successful download and display in the Alexa app:

Image requirements:
- Supported media types: JPEG or PNG.
- Minimum image resolution: 360 pixels along its shortest side.
- Set a URI expiration time. Amazon recommends that the URI remain valid for 10 minutes.
- For optimal performance, keep image file sizes to 60 KB on average.
Authentication and security requirements:
- The URI must not be publicly accessible.
- Your service must require authentication to access the image.
- Alexa supports access token authentication and sends the access token as part of the Authorization header field when downloading the image from the URI.
- Your service must perform 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 image.
HTTP specification details:
- Alexa doesn’t support URI redirects from the provided URI.
- 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}
- In response, your service returns the image with the Content-type header field set to one of the following media types: image/jpeg or image/png.
  If not specified, the default is image/png.
- If the URI becomes invalid or expires, return HTTP Status 410. On receipt of the error, Alexa retries the GetSnapshot directive to fetch a new URI.
Amazon estimates the queries per second (QPS) based on the minRefreshIntervalInSeconds value you send in the discovery response. Set the value to a low rate, such as 3600 seconds.

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. For security cameras and other cameras, use CAMERA for the display category. For doorbells with a camera, use both CAMERA and DOORBELL for the display categories. 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 criterion 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 add-on.	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
`preferOnDemandSnapshot`	Indicates that the camera should return a new snapshot, if supported. Otherwise, the camera can return a cached snapshot, if available. For doorbells with a camera, send the most recent snapshot captured during a wake event. 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 within 8 seconds. Include the URI to the snapshot image in the response. The following example shows a synchronous Snapshot response.

Snapshot response example

{
    "event": {
        "header": {
            "namespace": "Alexa.SmartVision.SnapshotProvider",
            "name": "Snapshot",
            "messageId": "Unique version 4 UUID",
            "correlationToken": "Opaque correlation token",
            "payloadVersion": "1.1"
        },
        "endpoint": {
            "endpointId": "Endpoint ID"
        },
        "payload": {
            "value": {
                "uri": "https://example.com/images/image1.jpg",
                "uriExpirationTime": "2024-03-15T13:10:00.00Z",
                "authenticationType": "ACCESS_TOKEN"
            },
            "timeOfSample": "2024-03-15T12:10:00.00Z",
            "uncertaintyInMilliseconds": 10000
        }
    }
}

GetSnapshot response payload

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.

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

Alexa.SmartVision.SnapshotProvider Interface 1.1

Snapshot image guidelines

Utterances

Reportable properties

Discovery

Configuration object

Discover response example

AddOrUpdateReport

AddOrUpdateReport event example

Directives

GetSnapshot

GetSnapshot directive example

GetSnapshot directive payload

GetSnapshot response

GetSnapshot response payload

GetSnapshot error handling

Change reporting

​Snapshot image guidelines

​Utterances

​Reportable properties

​Discovery

​Configuration object

​Discover response example

​AddOrUpdateReport

​AddOrUpdateReport event example

​Directives

​GetSnapshot

​GetSnapshot directive example

​GetSnapshot directive payload

​GetSnapshot response

​GetSnapshot response payload

​GetSnapshot error handling

​Change reporting

​Related topics

Snapshot image guidelines

Utterances

Reportable properties

Discovery

Configuration object

Discover response example

AddOrUpdateReport

AddOrUpdateReport event example

Directives

GetSnapshot

GetSnapshot directive example

GetSnapshot directive payload

GetSnapshot response

GetSnapshot response payload

GetSnapshot error handling

Change reporting

Related topics