Alexa for Apps V2 Skill Connection Request Reference

When you add Alexa for Apps V2 to your custom skill, you use a skill connection request to help connect your users to your app or website. For details about how to add Alexa for Apps to your skill, Add Alexa for Apps V2 to Your Custom Skill. For general information about the skill connection request and response format, see Request and Response JSON Reference.

Skill connection request payload examples

The following examples show payloads for Alexa for Apps V2 payload requests.

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

By default, when a customer makes a request on a mobile device, Alexa will directly launch the app. On non-mobile devices, Alexa will send a push notification with the provided link to the customer's phone.

In this example, the customer makes a request on a mobile device. Because the skill hasn't specified a preference between doing a direct launch or sending a notification, the resulting experience launches the app directly on the customer's phone.

{
   "version": "1.0",
   "sessionAttributes": {},
   "response": {
      "outputSpeech": {...},
      "card": {...},
      "reprompt": {...},
      "directives": [
================== ALEXA FOR APPS ADDITIONS START ==================
         {
            "type": "Connections.StartConnection",
            "uri": "connection://AMAZON.LinkApp/2",
            "input": {
               "links": {
                  "IOS_APP_STORE": {
                     "primary": {
                        "UNIVERSAL_LINK": {
                           "appIdentifier": "id123456789",
                           "url": "https://www.cityguide.com/search/search_terms=coffee"
                        }
                     }
                  },
                  "GOOGLE_PLAY_STORE": {
                     "primary": {
                        "UNIVERSAL_LINK": {
                           "appIdentifier": "com.cityguide.app",
                           "url": "https://www.cityguide.com/search/search_terms=coffee"
                        }
                     }
                  }
               },
               "prompt": {
                  "topic": "see your search results",
                  "directLaunchDefaultPromptBehavior": "SPEAK"
               }
            }
         }
================== ALEXA FOR APPS ADDITIONS END ====================
      ]
   }
}

Direct launch only - Android custom intent with intent extras

The following example shows a payload for a skill connection request that uses an ANDROID_CUSTOM_INTENT deep link. Because the skill only needs to launch the app directly on mobile, it explicitly sets the value of the sendToDevice.enabled property to false.

{
   "version": "1.0",
   "sessionAttributes": {},
   "response": {
      "outputSpeech": {...},
      "card": {...},
      "reprompt": {...},
      "directives": [
================== ALEXA FOR APPS ADDITIONS START ==================
         {
            "type": "Connections.StartConnection",
            "uri": "connection://AMAZON.LinkApp/2",
            "input": {
               "links": {
                  "GOOGLE_PLAY_STORE": {
                     "primary": {
                        "ANDROID_CUSTOM_INTENT": {
                           "appIdentifier": "com.cityguide.app",
                           "intentSchemeUri": 
intent:#Intent;package=com.cityguide.app;component=com.cityguide.app.SearchActivity;S.stringExtra=stringValue;i.intExtra=20;B.booleanExtra=true;end"
                        }
                     }
                  }
               },
               "prompt": {
                  "topic": "see your search detail"
               },
               "sendToDevice": {
                  "enabled": false
               }
            }
         }
================== ALEXA FOR APPS ADDITIONS END ====================
      ]
   }
}

Send to phone only - Android common intent and common URI scheme

The following example shows a payload for a skill connection request that uses both Android common intent and common URI scheme for deep links. It has chosen to be less intrusive and only needs to send a push notification and not have the app launched directly on the customer's phone. The skill therefore explicitly sets the value of directLaunch.enabled to false.

{
   "version": "1.0",
   "sessionAttributes": {},
   "response": {
      "outputSpeech": {...},
      "card": {...},
      "reprompt": {...},
      "directives": [
================== ALEXA FOR APPS ADDITIONS START ==================
         {
            "type": "Connections.StartConnection",
            "uri": "connection://AMAZON.LinkApp/2",
            "input": {
               "links": {
                  "GOOGLE_PLAY_STORE": {
                     "primary": {
                        "ANDROID_COMMON_INTENT": {
                           "intentName": "OPEN_SETTINGS",
                           "intentSchemeUri": "intent:#Intent;action=android.settings.WIFI_SETTINGS;end"
                        }
                     }
                  },
                  "IOS_APP_STORE": {
                     "primary": {
                        "COMMON_SCHEME": {
                           "scheme": "TEL",
                           "uri": "tel:1234567"
                        }
                     }
                  }
               },
               "prompt": {
                  "topic": "see your settings"
               },
               "directLaunch": {
                  "enabled": false
               }
            }
         }
================== 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/2",

Specifies the links that the skill sends. Links are grouped by catalogType. The currently supported catalogType values are "IOS_APP_STORE" and "GOOGLE_PLAY_STORE".

Field Description Type Required

links.IOS_APP_STORE

Links for the IOS_APP_STORE catalog type.

Object

No, if links.GOOGLE_PLAY_STORE is specified. Yes otherwise.

links.IOS_APP_STORE.primary

The primary link. See Deep link reference.

One of:
UNIVERSAL_LINK,
ANDROID_CUSTOM_INTENT,
CUSTOM_SCHEME,
WEBSITE_LINK,
COMMON_SCHEME,
ANDROID_COMMON_INTENT,
ANDROID_PACKAGE.

Yes

links.IOS_APP_STORE.fallback

The fallback link. See Deep link reference.

One of: UNIVERSAL_LINK, WEBSITE_LINK.

No

links.GOOGLE_PLAY_STORE

Links for the GOOGLE_PLAY_STORE catalog type.

Object

No, if links.IOS_APP_STORE is specified. Yes otherwise.

links.GOOGLE_PLAY_STORE.primary

The primary link. See Deep link reference.

One of: UNIVERSAL_LINK, ANDROID_CUSTOM_INTENT, CUSTOM_SCHEME, WEBSITE_LINK, COMMON_SCHEME, ANDROID_COMMON_INTENT, ANDROID_PACKAGE.

Yes

links.GOOGLE_PLAY_STORE.fallback

The fallback link. See Deep link reference.

One of: UNIVERSAL_LINK, WEBSITE_LINK.

No

prompt object in the input payload

The prompt object specifies custom Alexa prompts for your app. This object is optional.

Field Description Type Required

prompt.topic

A topic string that describes the link. Alexa uses the topic string to tell the customer what the link is for. This should be in a verb-first format, for example, "see your messages".

String

Yes

prompt.directLaunchDefaultPromptBehavior

Used to indicate whether to suppress the direct launch helper prompt of "Here's <friendly name>." for mobile requests when the phone is unlocked. One of SPEAK, SUPPRESS.

Enum

No

Field Description Type Required

enabled

Set to true to allow directly launching the app on mobile devices, or false otherwise. The default value is true.

Boolean

Yes

Field Description Type Required

enabled

Set to true to allow sending a notification for this request, or false otherwise. The default value is true.

Boolean

Yes

"UNIVERSAL_LINK": {
    "appIdentifier": "id123456789", # if it’s Android then "com.someapp"
    "url": "https://www.cityguide.com/search/search_terms=coffee",
}
"ANDROID_CUSTOM_INTENT": {
    "appIdentifier": "com.someapp",
    "intentSchemeUri": "intent:#Intent;package=com.someapp;action=com.example.myapp.MY_ACTION;i.some_int=100;S.some_str=hello;end"
}
"CUSTOM_SCHEME": {
    "appIdentifier": "id123456789", # or "com.someapp"
    "uri": "twitter://feeds/"
}
"WEBSITE_LINK": {
    "url": "https://www.cityguide.com/search/search_terms=coffee"
}
"COMMON_SCHEME": {
    "scheme": "TEL",
    "uri": "tel:8001234567"
}
"ANDROID_PACKAGE": {
    "packageIdentifier": "com.someapp"
}
"ANDROID_COMMON_INTENT": {
    "intentName": :"OPEN_SETTINGS",
    "intentSchemeUri": "intent:#Intent;action=android.settings.WIFI_SETTINGS;end"
}
Field Description Type Required

UNIVERSAL_LINK

Object to represent a universal link that can be launched in a specific app.

Object

No

UNIVERSAL_LINK.appIdentifier

The target app by which the link should be opened.

String

Yes

UNIVERSAL_LINK.url

The URL for the universal link.

String

Yes

ANDROID_CUSTOM_INTENT

Object to represent an Android custom intent that can be launched in a specific app.

Object

No

ANDROID_CUSTOM_INTENT.appIdentifier

The target app by which the link should be opened.

String

Yes

ANDROID_CUSTOM_INTENT.intentSchemeUri

String in the intent scheme for an Android intent.

String

Yes

CUSTOM_SCHEME

Object to represent a custom scheme that can be launched in a specific app.

Object

No

CUSTOM_SCHEME.appIdentifier

The target app by which the link should be opened.

String

Yes

CUSTOM_SCHEME.uri

The URI for link. For android, the scheme is "geo:". For iOS, the scheme is "maps:".

String

Yes

WEBSITE_LINK

Object to represent a web link that can be opened in a browser.

Object

No

WEBSITE_LINK.url

The URL for link.

String

Yes

COMMON_SCHEME

Object to represent a common scheme URI that can open by the system. Alexa for Apps validates the fields in this object at runtime based on the scheme. For example, if you skill declares support for TEL, Alexa for Apps verifies that the uri value contains "tel:", followed by numbers.

Object

No

COMMON_SCHEME.scheme

The scheme: MAPS or TEL.

Enum

Yes

COMMON_SCHEME.uri

The URL for the scheme.

String

Yes

ANDROID_PACKAGE

Object to represent an Android package.

Object

No

ANDROID_PACKAGE.packageIdentifier

Package name for the Android app.

String

Yes

ANDROID_COMMON_INTENT

Object to represent an Android common intent that can be opened by the default apps. Alexa for Apps validates the fields in this object at runtime based on the linkedAndroidCommonIntents.intentName value declared in the manifest. For example, if this value is SHOW_IN_MAP, the action value must be "android.intent.action.VIEW", and the data value must start with "geo:".

Object

No

ANDROID_COMMON_INTENT.intentName

Intent name. This should match the linkedAndroidCommonIntents.intentName value in the skill manifest. One of: SHOW_IN_MAP, ADD_CALENDAR_EVENT, PLAY_MEDIA, START_PHONE_CALL, OPEN_SETTINGS

Enum

Yes

ANDROID_COMMON_INTENT.intentSchemeUri

String in the intent scheme for an Android intent.

String

Yes

Skill connection response payload example for directLaunch

The following is an example skill connection response for directLaunch.

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

Skill connection response payload example for sendToDevice

The following is an example skill connection response for sendToDevice.

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

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 the beta program, or it's 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 the time of the request. For example, 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 installed version isn't compatible with the specified action.200
Status Error code Description

400

UNSUPPORTED_DEVICE

Device not supported

403

UNAUTHORIZED

Device
not
supported

400

UNSUPPORTED_DEVICE

Device not supported