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.

Payload examples for a skill connection request

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 directly launches the app. On non-mobile devices, Alexa sends 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 example

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 a mobile device, 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 example

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. The input payload groups links 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. For details, 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. For details, 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. For details, 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. For details, 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 string 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

The following examples show the format for deep link objects.

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

The following tables describes the fields of deep link objects.

Field Description Type Required

UNIVERSAL_LINK

Object to represent a universal link that customers can launch in a specific app.

Object

No

UNIVERSAL_LINK.appIdentifier

The target app in which customers open the link.

String

Yes

UNIVERSAL_LINK.url

The URL for the universal link.

String

Yes

ANDROID_CUSTOM_INTENT

Object to represent an Android custom intent that customers can launch in a specific app.

Object

No

ANDROID_CUSTOM_INTENT.appIdentifier

The target app in which customers open the link.

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 customers can launch in a specific app.

Object

No

CUSTOM_SCHEME.appIdentifier

The target app in which customers open the link.

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 customers can open in a browser.

Object

No

WEBSITE_LINK.url

The URL for the link.

String

Yes

COMMON_SCHEME

Object to represent a common scheme URI that the system can open. Alexa for Apps validates the fields in this object at runtime based on the scheme. For example, if your 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 the default apps can open. 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. For those actions that failed, provide an error code from the codes listed in the following table, with an explanation for the error.

Error codeDetailsStatus code
UNSUPPORTED_DEVICEDevice not supported.400
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 customer 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 customer has the app, 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