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.
Universal links – IOS_APP_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": "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 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 |