Alexa for Apps Skill Connection Request Reference

Important: Alexa for Apps is a developer preview and might change as Amazon receives feedback and iterates on the feature. To use this feature, you must register for the preview. If you have questions or feedback about Alexa for Apps, please email alexaforapps-help@amazon.com.

When you add Alexa for Apps to your custom skill, you use added skill connection request fields to help connect your users to your skill. For details about how to add Alexa for Apps to your skill, Add Alexa for Apps to Your Custom Skill. For the full skill connection request and response format, see Request and Response JSON Reference.

Skill connection request payload example

The following example shows a payload for a skill connection request that uses universal links.

Universal links – `IOS_APP_STORE` payload example

Important: In your own payloads, omit the lines "ALEXA FOR APPS ADDITIONS START" and "ALEXA FOR APPS ADDITIONS END".

{
   "version": "1.0",
   "sessionAttributes": {},
   "response": {
      "outputSpeech": {...},
      "card": {...},
      "reprompt": {...},
      "directives": [
================== ALEXA FOR APPS ADDITIONS START ==================
         {
         "type": "Connections.StartConnection",
         "uri": "connection://AMAZON.LinkApp/1",
         "input": {
            "catalogInfo": {
               "identifier": "id123456789",
               "type": "IOS_APP_STORE"
            },
            "actions": {
               "primary": {
                  "type": "UNIVERSAL_LINK",
                  "link": "https://www.cityguide.com/search/search_terms=coffee"
               }
            },
            "prompts": {
               "onAppLinked": {
                  "prompt": {
                     "ssml": "<speak>Okay</speak>",
                     "type": "SSML"
                  },
               "defaultPromptBehavior": "SUPPRESS" // This suppresses an added helper TTS of "Here's <app name>."
               },
               "onScreenLocked": {
                  "prompt": {
                     "text": "There's a Cupcake Shop and a My Coffee Shop within a mile of you.",
                     "type": "PlainText"
                     }
                  }
               }
            }
         },
================== ALEXA FOR APPS ADDITIONS END ====================
      ]
   }
}

Skill connection request properties reference

`type` and `uri` values

The top-level type and uri values are always the same. Alexa skill connections requires these values. Use the values exactly as they appear in the following example.

"type": "Connections.StartConnection",
"uri": "connection://AMAZON.LinkApp/1",

`catalogInfo` object in the `input` payload

The catalogInfo object contains the information required for Android or iOS app link requests.

Field	Description	Type	Required
`type`	`IOS_APP_STORE` or `GOOGLE_PLAY_STORE`	String enumeration value	Yes
`identifier`	The identifier for your app in the iOS App Store or Google Play Store. For iOS apps, it's a numeric identifier; for example, `id123456789`. For Android intents, it's typically the package name; for example, `com.cityguide.android.ctgdmobile`.	String	Yes

`actions` object in the `input` payload

The actions object specifies the requested links for the primary and fallback actions. The primary object is required. The fallback object is optional.

Field	Description	Type	Required
`primary.type`	Specifies the deep link type for the primary action: `UNIVERSAL_LINK`, `CUSTOM_SCHEME`, `ANDROID_INTENT`, or `ANDROID_PACKAGE`	String enumeration value	Yes
`fallback.type`	Specifies the deep link type for the fallback action. This is currently limited to `UNIVERSAL_LINK`.	String enumeration value	Yes (if a `fallback` object is specified)
`primary.link`	The deep link (in the previous example, the `https` URI) to send the user to, if the user hasn't installed your app on the their device.	String	Yes
`fallback.link`	The deep link to send the user to, if the user hasn't installed your app on the their device. For App Store fallbacks, you provide the full URI to the App Store link instead of a website.	Yes (if a `fallback` object is specified)

`prompts` object in the `input` payload

The prompts object specifies properties of Alexa prompts for your app. This object is optional and can be provided for onAppLinked or onScreenLocked. If provided, the prompts object must have a prompt property, which in turn must have a type field value of PlainText or SSML. If type is SSML, the prompt property must have an ssml value. If type is PlainText, the prompt property must have a text value.

`prompts` properties for `onAppLinked`

These properties specify the prompts for all cases except when the user's device is locked.

Field	Description	Type	Required
`prompt.type`	`Plaintext` or `SSML`. `SSML` allows you to apply various effects such as Amazon Polly voices, sound effects, and prosody.	String enumeration value	Yes
`prompt.text`	If `prompt.type` is `Plaintext`, this field contains locale-specific custom text for the custom voice response for Alexa to play before the deep link is sent. Use a framework such as `i18next` to simplify your localization code. See How to Localize Your Alexa Skills.	String	Yes (if `prompt.type` is `Plaintext`)
`prompt.ssml`	If `prompt.type` is `SSML`, this field contains locale-specific SSML for the custom voice response for Alexa to play when the user's device is unlocked.	String enumeration value	Yes (if `prompt.type` is `SSML`)
`prompt.defaultPromptBehavior`	By default, when the user's device is unlocked, after the text in `prompt.text`, Alexa says, "Here's `\<app name\>`." This phrase is called the helper TTS. To suppress the helper TTS, set this property to `SUPPRESS`. In the previous example, because the helper TTS is suppressed, Alexa says only "Okay!" before the deep link is sent.	String	No

Warning: The helper TTS of "Here's <app name>." is meant to help users understand that they are transitioning from a voice experience, into your apps and websites. Consider how the user invokes your skill and what they're expecting to see as a result. If it's significantly different, consider either keeping the helper TTS or letting the user know what's about to happen: "I found a new coffee shop near you with a five-star rating. Here's our City Guide Picks review site to learn more." See the Alexa for Apps Design Guide for more details.

`prompts` properties for `onScreenLocked`

These properties specify the prompts for when the user's device is locked.

Field	Description	Type	Required
`prompt.type`	`Plaintext` or `SSML`. `SSML` allows you to apply various effects such as Amazon Polly voices, sound effects, and prosody.	String enumeration value	Yes
`prompt.text`	If `prompt.type` is `Plaintext`, this field contains locale-specific custom text for the custom voice response for Alexa to play when the user's device is locked. Use a framework such as `i18next` to simplify your localization code. See How to Localize Your Alexa Skills.	String	Yes (if `prompt.type` is `Plaintext`)
`prompt.ssml`	If `prompt.type` is `SSML`, this field contains locale-specific SSML for the custom voice response for Alexa to play when the user's device is locked.	String enumeration value	Yes (if `prompt.type` is `SSML`)
`prompt.defaultPromptBehavior`	By default, when the user's device is locked, after the response in `prompt.text` or `prompt.ssml`, Alexa says, "To continue, please unlock your device." This phrase is called the helper TTS. To suppress the helper TTS, set this property to `SUPPRESS`. Although Amazon generally doesn't recommend suppressing, because it provides necessary guidance to the user, you might do so to make that guidance flow more naturally. For example, your custom text might say, "I found three coffee shops near you. Unlock your device to see their locations." In the previous example, this isn't suppressed, so Alexa says, "There's a Cupcake Shop and a My Coffee Shop within a mile of you. To continue, please unlock your device."	String	No

Warning: If you suppress the helper TTS for locked device scenarios, you must provide guidance to the user that they need to unlock their device to continue. If the user's device is locked when your skill sends an Alexa app link request, the deep link is not sent unless the user unlocks their device. For security purposes, that deep link request also expires after a short period of time. Therefore, the helper TTS of "To continue, please unlock your device" provides necessary guidance to the user that they need to unlock their device before getting the result they wanted. If you suppress the helper TTS, you must provide guidance to the user in your custom text. "I found three coffee shops near you. Unlock your device to see more in the app." For more details, see the Alexa for Apps Design Guide.

Additional skill connection request payload examples

Important: In your own payloads, omit the lines "ALEXA FOR APPS ADDITIONS START" and "ALEXA FOR APPS ADDITIONS END".

Custom scheme - `GOOGLE_PLAY_STORE` payload example

{
   "version": "1.0",
   "sessionAttributes": {},
   "response": {
      "outputSpeech": {...},
      "card": {...},
      "reprompt": {...},
      "directives": [
================== ALEXA FOR APPS ADDITIONS START ==================
         {
         "type": "Connections.StartConnection",
         "uri": "connection://AMAZON.LinkApp/1",
         "input": {
            "catalogInfo": {
               "identifier": "com.cityguide.android.ctgdmobile",
               "type": "GOOGLE_PLAY_STORE"
            },
            "actions": {
               "primary": {
                  "type": "CUSTOM_SCHEME",
                  "link": "ctgd://search/search_terms=coffee"
               }
            },
            "prompts": {
               "onAppLinked": {
                  "prompt": {
                     "ssml": "<speak>Okay</speak>",
                     "type": "SSML"
                  },
               "onScreenLocked": {
                  "prompt": {
                     "text": "There's a Cupcake Shop and a My Coffee Shop within a mile of you.", // A default helper TTS of "To
continue, please unlock your device," plays after this.
                     "type": "PlainText"
                     }
                  }
               }
            }
         },
================== ALEXA FOR APPS ADDITIONS END ====================
      ]
   }
}

Android intent payload example

{
   "version": "1.0",
   "sessionAttributes": {},
   "response": {
      "outputSpeech": {...},
      "card": {...},
      "reprompt": {...},
      "directives": [
================== ALEXA FOR APPS ADDITIONS START ==================
         {
         "type": "Connections.StartConnection",
         "uri": "connection://AMAZON.LinkApp/1",
         "input": {
            "catalogInfo": {
               "identifier": "com.cityguide.android.ctgdmobile",
               "type": "GOOGLE_PLAY_STORE"
            },
            "actions": {
               "primary": {
                  "type": "ANDROID_INTENT",
                  "link": "intent:#Intent;action=com.cityguide.android.ctgdmobile.actions.SEARCH_ACTION;package=com.cityguide.android.ctgdmobile;S.query=coffee;end;"
               },
               "fallback": {
                  "type": "UNIVERSAL_LINK",
                  "link": "http://www.cityguide.com/search?search_terms=coffee" // Launches cityguide.com
               }
            },
            "prompts": {
               "onAppLinked": {
                  "prompt": {
                     "text": "Okay!",
                     "type": "PlainText"
                  },
                  "defaultPromptBehavior": "SUPPRESS" // This suppresses an added helper TTS of "Here's <app name>."
               },
               "onScreenLocked": {
                  "prompt": {
                     "ssml": "<speak>There's a Cupcake Shop and a My Coffee Shop within a mile of you.</speak>", 
                     "type": "SSML"
                     }
                     // Because defaultPromptBehavior in not set to SUPPRESS in this example, the default helper TTS of "To continue, please unlock your device," plays after the previous onScreenLocked SSML response.
                  }
               }
            }
         },
================== ALEXA FOR APPS ADDITIONS END ====================
      ]
   }
}

Android app launch example

{
   "version": "1.0",
   "sessionAttributes": {},
   "response": {
      "outputSpeech": {...},
      "card": {...},
      "reprompt": {...},
      "directives": [
================== ALEXA FOR APPS ADDITIONS START ==================
         {
         "type": "Connections.StartConnection",
         "uri": "connection://AMAZON.LinkApp/1",
         "input": {
            "catalogInfo": {
               "identifier": "com.cityguide.android.ctgdmobile",
               "type": "GOOGLE_PLAY_STORE"
            },
            "actions": {
               "primary": {
                  "type": "ANDROID_PACKAGE",
                  "link": "com.cityguide.android.ctgdmobile"
               }
            },
            "prompts": {
               "onAppLinked": {
                  "prompt": {
                     "text": "Okay!",
                     "type": "PlainText"
                     },
                     "defaultPromptBehavior":"SUPPRESS" // This suppresses the default helper TTS of "Here's City Guide,"
   so the user just hears "Okay!" before being taken to the app.
                  },
               "onScreenLocked": {
                  "prompt": {
                     "text": "There's a Cupcake Shop and a My Coffee Shop within a mile of you.", // A default helper TTS of "To
continue in the app, please unlock your device," plays after this.
                     "type": "PlainText"
                     }
                  }
               }
            }
         },
================== ALEXA FOR APPS ADDITIONS END ====================
      ]
   }
}

Skill connection response payload example

The following is an example skill connection response:

{
   "type": "SessionResumedRequest"
   "requestId": "<string>",
   "timestamp": "<string>",
   "locale": "<string>",
   "cause":
   {
      "type": "ConnectionCompleted",
      "token": "1234",
      "status": {"code": "200","message": "OK"},
      "result": {
         "primary": {
            "status": "FAILURE",
            "errorCode": "APP_INCOMPATIBLE"
         },
         "fallback": {
            "status": "SUCCESS"
         }
      }
   }
}

Skill connection response reference

In the skill connection response payload, the cause.status property refers to the skill connection itself and not to the results of the deep link attempt. The result payload uses the cause.result.primary.status and cause.result.fallback.status properties to tell your skill whether the primary and fallback actions succeeded or failed, and for those that failed, provide an error code per the following table, with an explanation for the error.

Note: The status code is based on the last attempted action's outcome.

Error Code	Details	Status code
`UNSUPPORTED_DEVICE`	Device not supported	400
`UNAUTHORIZED`	The skill is unauthorized, for example it's not enrolled in developer preview or is trying to deep link to an app that's not declared in the manifest.	403
`INVALID_REQUEST`	Payload invalid	400
`INVALID_STATE`	The device state was invalid at time of request, for example if the user was driving or they never unlocked their device.	200
`UNKNOWN`	Indicates a service-side error launching the deep link on the mobile device.	500
`APP_NOT_INSTALLED`	App not installed	200
`APP_INCOMPATIBLE`	(Android only) The app is installed, but the version installed isn't compatible with the provided action	200

Alexa for Apps Skill Connection Request Reference

Skill connection request payload example

Universal links – IOS_APP_STORE payload example

Skill connection request properties reference

type and uri values

catalogInfo object in the input payload

actions object in the input payload

prompts object in the input payload

prompts properties for onAppLinked

prompts properties for onScreenLocked