Alexa.Launcher Interface (VSK Fire TV)

Select the software version in the dropdown navigation.

Alexa.Launcher version 3.1 introduces custom UI shortcuts. Define the voice shortcuts that your endpoint supports to enable the user to navigate through your UI. You can specify your custom UI shortcuts in your discovery response.

For the list of locales that are supported for the Launcher interface, see List of Capability Interfaces and Supported Locales.

Note: The Alexa.Launcher interface is available for cloudside and app-only integrations, but we recommend the app-only integration.

Directives

LaunchTarget directive

This is a request to navigate to a custom shortcut. The shortcut requested by the user will be matched to the partner's provided list of targets. If there's a match, Alexa will send the name, identifier, and sourceID back to the partner.

User: Alexa, go to <Custom Shortcut>

LaunchTarget directive example

{
    "directive": {
        "header": {
            "correlationToken": "an opaque correlation token",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "name": "LaunchTarget",
            "namespace": "Alexa.Launcher",
            "payloadVersion": "3.1"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "some-access-token"
            },
            "endpointId": "endpoint id",
            "cookie": {}
        },
        "payload": {
            "name": "Custom Shortcut",
            "identifier": "partner.custom.shortcut.identifier",
            "sourceId": "DISCOVERY"
            }
        }
    }
}

LaunchTarget directive parameters

Property	Description	Type	Required
`name`	The name associated with the identifier.	String	Yes
`identifier`	The identifier for the custom shortcut.	String	Yes
`sourceId`	Uniquely identifies the catalog. Valid values for predefined catalogs: `ALEXA_VIDEO_SHORTCUT_STORE`, `ALEXA_VIDEO_APP_STORE`. Valid value for custom shortcuts: `DISCOVERY`.	String	Yes
`experience.mode`	Suggests the mode to display the requested results. `VOICE_OPTIMIZED` indicates voice-centric results, such as a shorter search result list. Use `DEFAULT` when you don't support the value of mode. Valid values: `DEFAULT`, `VOICE_OPTIMIZED`	String	No

LaunchTarget response example

If you handle a LaunchTarget directive successfully, respond with an Alexa.Response event. Include the values of the target property in the context object.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
            "endpointId": "endpoint id"
        },
        "payload": {}
    },
    "context": {
        "properties": [
            {
                "namespace": "Alexa.Launcher",
                "name": "target",
                "value": {
                    "name": "Custom Shortcut",
                    "identifier": "partner.custom.shortcut.identifier"
                },
                "timeOfSample": "2021-12-01T18:20:50Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2021-12-01T18:20:50Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

See Alexa.Discovery response example to see how to send payload targets to launch apps and shortcuts.

Shortcut name requirements

Do not include carrier phrases in your shortcuts because Alexa handles them. Example: use "settings" as opposed to "go to settings". Full list of carrier phrases to exclude from your shortcut names are listed below.
- navigate to
- go
- go to
- select
- pick
- choose
- click
- click on
- hit
- launch
- take me/us to
- open
- show
- show me/us
- display
Use all lower case when defining shortcut names.
Shortcut names should be alphanumeric.
" Home" is a reserved utterance and will always default to Fire TV home.
Variations of shortcut names will NOT be covered. If you want “go to movie” and “go to movies” to work, then you need to include both “movie” and “movies” as shortcut names that point to the same identifier.

Note: There is a limit of 50 shortcuts.

Events and Properties

Reportable Properties

Property Name	Type	Description
target	Target	The launched app or shortcut.

Configuration object

In addition to the usual discovery response fields, for Alexa.Launcher, include a configuration object that contains the following fields.

Property	Description	Type	Required
`catalogs`	Identifies the catalogs to import. Only include the catalogs that support the language configured on the device. If your endpoint doesn't support any predefined catalogs, include an empty array. Maximum: 5 catalogs. Valid values: `ALEXA_VIDEO_SHORTCUT_STORE`, `ALEXA_VIDEO_APP_STORE`.	Array of `Catalog` objects	Yes
`targets`	Include the custom UI shortcuts that your endpoint supports. If your skill defines both custom shortcuts and the predefined shortcut catalog, Alexa tries to find a match in the targets field first, and then searches the predefined shortcut catalog. If your endpoint doesn't support custom shortcuts, include an empty array. Maximum: 50 shortcuts.	Array of `Target` objects	Yes

Catalog object

The Catalog object defines the predefined catalogs that the endpoint supports.

Important: Version 3.1 adds the Catalog object to support catalog ingestion. At this time, custom catalogs aren't supported.

The following table shows the definition of the Catalog object.

Property	Description	Type	Required
`sourceId`	Uniquely identifies the catalog. If your endpoint supports the predefined application catalog, set to `ALEXA_VIDEO_APP_STORE`. If your endpoint supports the predefined UI shortcut catalog, set to `ALEXA_VIDEO_SHORTCUT_STORE`. For the application and short targets in the predefined catalogs, see Launch Target Reference.	String	Yes
`targets`	Include the custom UI shortcuts that your endpoint supports. If your skill defines both custom shortcuts and the predefined shortcut catalog, Alexa tries to find a match in the targets field first, and then searches the predefined shortcut catalog. If your endpoint doesn't support custom shortcuts, include an empty array. Maximum: 50 shortcuts.	Array of `Target` objects	Yes

Target object

The Target object contains a name and identifier that represents a custom UI shortcut that you define.

The following example shows a custom UI shortcut target.

{
  "name": "target",
  "value": {
      "name": "Watchlist",
      "identifier": "custom.shortcut.id.0000"
    }
}

The following table shows the definition of the Target object.

Property	Description	Type	Required
`name`	Name of the custom shortcut. The custom shortcut name must contain alphanumeric characters only.	String	Yes
`identifier`	Custom identifier associated with the shortcut.	String	Yes

Response

Send a Response when you successfully handle a LaunchTarget directive.

Example Response

The following example shows a Response message. Report the value of the target property in the context of the message.

Copied to clipboard.

{
    "context": {
        "properties": [
            {
                "name": "target",
                "namespace": "Alexa.Launcher",
                "timeOfSample": "2017-05-06T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0,
                "value": {
                     "name": "Custom Shortcut",
                     "identifier": "partner.custom.shortcut.identifier"
                }
            }
        ]
    },
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8pt90jSqg==",
            "messageId": "abc-123-def-456",
            "name": "Response",
            "namespace": "Alexa",
            "payloadVersion": "3"
        },
        "payload": {}
    }
}

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason. See the Error Handling documentation for more information.

With Alexa.Launcher v3.0, third parties can launch a target on their device. This is useful for launching their application or a shortcut, such as settings.

The Alexa.Launcher interface exposes directives for launching:

Application targets such as Prime Video
GUI shortcut targets such as Home or Settings

Directives to launch targets include a name and identifier from a list of predefined launch targets. You should review the list of launch targets and make sure your skill can correctly resolve items that support the skill's functionality.

For the list of locales that are supported for the Launcher interface, see List of Capability Interfaces and Supported Locales.

Note: The Alexa.Launcher interface is available for cloudside integration only.

Directives

LaunchTarget

Request to launch a specified application or shortcut. The application or shortcut named by the user is matched to an identifier in a predefined launch target list list and the name and identifier is sent in the request.

User: Alexa, launch Prime Video

Example: Launch Prime Video

{
    "directive": {
        "endpoint": {
              "scope": {
                "type": "BearerToken",
                "token": "some-access-token"
              },
              "endpointId": "endpoint-001",
              "cookie": {}
            },
        },
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8pt90jSqg==",
            "messageId": "abc-123-def-456",
            "name": "LaunchTarget",
            "namespace": "Alexa.Launcher",
            "payloadVersion": "3"
        },
        "payload": {
            "identifier": "amzn1.alexa-ask-target.app.72095",
            "name": "Prime Video"
        }
    }
}

Payload details

Property	Description	Type	Required
`identifier`	The identifier for the item to launch. Application identifiers contain `app`, and shortcut identifiers contain `shortcut`. For a complete list of identifiers see the Launch Target Reference	String	Yes
`name`	The name associated with the identifier.	String	Yes