Developer Console

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.

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.

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.

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:

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.

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

Events and Properties

Reportable Properties

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

Response

Send an 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.

{
    "context": {
        "properties": [
            {
                "name": "target",
                "namespace": "Alexa.Launcher",
                "timeOfSample": "2017-05-06T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0,
                "value": {
                    "identifier": "amzn1.alexa-ask-target.app.72095",
                    "name": "Prime Video"
                }
            }
        ]
    },
    "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.


Last updated: 1-25-2022