Alexa for Apps V2 Skill Connection Request Reference

Note: Alexa for Apps V2 is a private beta and might change as Amazon receives feedback and iterates on the feature. To use this feature, you must register for the private beta program. If you have questions or feedback about Alexa for Apps, contact your Amazon Business Development representative, or email alexaforapps-help@amazon.com.

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.

Default link behavior – Universal links payload example

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.

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/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",

`links` object in the `input` payload

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

`directLaunch` object in the `input` payload

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

`sendToDevice` object in the `input` payload

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

Deep link examples

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

Deep link reference

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.

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 the beta program, or it's 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 the time of the request. For example, 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 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

Alexa for Apps V2 Skill Connection Request Reference

Skill connection request payload examples

Default link behavior – Universal links payload example

Direct launch only - Android custom intent with intent extras

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

Skill connection request properties reference

type and uri values

links object in the input payload

prompt object in the input payload

directLaunch object in the input payload

sendToDevice object in the input payload