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