Alexa for Apps Skill Connection Request Reference

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.

{
   "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

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

Additional skill connection request payload examples

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.

Error CodeDetailsStatus code
UNSUPPORTED_DEVICEDevice not supported400
UNAUTHORIZEDThe 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_REQUESTPayload invalid400
INVALID_STATEThe device state was invalid at time of request, for example if the user was driving or they never unlocked their device.200
UNKNOWNIndicates a service-side error launching the deep link on the mobile device.500
APP_NOT_INSTALLEDApp not installed200
APP_INCOMPATIBLE(Android only) The app is installed, but the version installed isn't compatible with the provided action200