Alexa for Apps Skill Connection Request Reference

When you add Alexa for Apps 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 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 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 user 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 user's phone.

In this example, the user 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 user'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 user'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,
CUSTOM_SCHEME,
WEBSITE_LINK,
COMMON_SCHEME.

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

Object

No

UNIVERSAL_LINK.appIdentifier

The target app in which users 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 users can launch in a specific app.

Object

No

ANDROID_CUSTOM_INTENT.appIdentifier

The target app in which users 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 users can launch in a specific app.

Object

No

CUSTOM_SCHEME.appIdentifier

The target app in which users 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 users 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

Payload examples and reference for a skill connection request response

There are three different skill connection response types that you can receive from Send to Phone: one for directLaunch requests (where Alexa opens the app directly on a phone), one for sendToDevice requests (where a user starts on an Echo device and gets a push notification flow to send to the user's phone), and one for when your request fails before either of the other two flows is taken.

Payload example for directLaunch response

The following example shows the format for the payload you receive for directLaunch.

{
   "type": "SessionResumedRequest",
   "requestId": "<string>",
   "timestamp": "<string>",
   "locale": "<string>",
   "cause":
   {
      "type": "ConnectionCompleted",
      "token": "1234",
      "status": {
         "code": "<see table>",
         "message": "<see table>"
      },
      "result": {
         "directLaunch": {
            "primary": {
               "status": "<see table>",
               "errorCode": "<see table>"
            },
            "fallback": {
                "status": "<see table>",
                "errorCode": "<see table>"
            }
         }
      }
   }
}

Payload reference for directLaunch response

The following table lists the possible responses you can receive in the fields labeled "see table" in the preceding example. The fallback property is present only if fallback was attempted; this happens when either the app associated with the primary link isn't installed or (for Android apps) the app version isn't compatible with the deep link provided.

Skill Connections code Skill Connections message directLaunch primary status directLaunch primary errorCode directLaunch fallback status directLaunch fallback errorCode

400

Device doesn't support AppLink or requested catalog type.

FAILURE

UNSUPPORTED_DEVICE

N/A

N/A

500

Unknown error was received

FAILURE

UNKNOWN

N/A

N/A

200

Device is in invalid state.

FAILURE

INVALID_STATE

N/A

N/A

200

Request was successfully fulfilled.

SUCCESS

N/A

N/A

N/A

200

Fallback action was successfully rendered.

FAILURE

APP_NOT_INSTALLED

SUCCESS

N/A

200

Fallback action was successfully rendered.

FAILURE

APP_INCOMPATIBLE

SUCCESS

SUCCESS

500

Connection completed. Fallback action failed.

FAILURE

APP_NOT_INSTALLED

FAILURE

UNKNOWN

200

Connection completed. Fallback action failed.

FAILURE

APP_NOT_INSTALLED

FAILURE

APP_NOT_INSTALLED

200

Connection completed. Fallback action failed.

FAILURE

APP_NOT_INSTALLED

FAILURE

APP_INCOMPATIBLE

200

Connection completed. Fallback action failed.

FAILURE

APP_NOT_INSTALLED

FAILURE

INVALID_STATE

500

Connection completed. Fallback action failed.

FAILURE

APP_INCOMPATIBLE

FAILURE

UNKNOWN

200

Connection completed. Fallback action failed.

FAILURE

APP_INCOMPATIBLE

FAILURE

APP_NOT_INSTALLED

200

Connection completed. Fallback action failed.

FAILURE

APP_INCOMPATIBLE

FAILURE

APP_INCOMPATIBLE

200

Connection completed. Fallback action failed.

FAILURE

APP_INCOMPATIBLE

FAILURE

INVALID_STATE

200

Connection completed. No fallback action was provided.

FAILURE

UNKNOWN

N/A

N/A

Payload example for sendToDevice response

The following example shows the format for the payload you receive for sendToDevice.

{
   "type": "SessionResumedRequest",
   "requestId": "<string>",
   "timestamp": "<string>",
   "locale": "<string>",
   "cause":
   {
      "type": "ConnectionCompleted",
      "token": "1234",
      "status": {
         "code": "<see table>",
         "message": "<see table>"
      },
      "result": {
         "sendToDevice": {
            "status": "<see table>",
            "errorCode": "<see table>"
         }
      }
   }
}

Payload reference for sendToDevice response

The following table lists the possible responses you can receive in the fields labeled "see table" in the preceding example. Note that the errorCode field generally refers to whether the push notification and the activity card were both attempted and/or sent successfully. One reason Alexa for Apps might not attempt sending a push notification is if the user disabled push notifications for the Alexa App, or the user declined to enable the notification for your skill. The Skill Connections response code indicates whether the connection call succeeded. The sendToDevice status indicates whether sending the link was successful.

Skill Connections code Skill Connections message sendToDevice status sendToDevice errorCode

200

Notification wasn't attempted.

FAILURE

NOTIFICATION_NOT_ATTEMPTED

200

Alexa for Apps attempted to send activity card and succeeded.

SUCCESS

CARD_ATTEMPTED_AND_SENT

500

Alexa for Apps attempted to send activity card and failed.

FAILURE

CARD_ATTEMPTED_AND_FAILED

200

Alexa for Apps attempted to send activity card and push notification, but only succeeded in sending the activity card.

SUCCESS

ALL_ATTEMPTED_CARD_SENT

200

Alexa for Apps attempted to send activity card and push notification, but only succeeded in sending the push notification.

SUCCESS

ALL_ATTEMPTED_PUSH_SENT

200

Alexa for Apps attempted to send activity card and push notification, and succeeded in sending both.

SUCCESS

ALL_ATTEMPTED_ALL_SENT

500

Alexa for Apps attempted to send activity card and push notification, and both attempts failed.

FAILURE

ALL_ATTEMPTED_ALL_FAILED

500

An unknown error occurred.

FAILURE

UNKNOWN

Payload example for when request fails early

The following example shows the format for the payload you receive if the request exits before any flow is determined.

{
   "type": "SessionResumedRequest",
   "requestId": "<string>",
   "timestamp": "<string>",
   "locale": "<string>",
   "cause":
   {
      "type": "ConnectionCompleted",
      "token": "1234",
      "status": {
         "code": "<see table>",
         "message": "<see table>"
      }
   }
}

Payload reference for when request fails early

The following table lists the possible responses you can receive in the fields labeled "see table" in the preceding example.

Skill Connections code Skill Connections message Description

403

Skill not allowlisted.

The skill is not allow-listed for Alexa for Apps Send to Phone.

500

Unknown error occurred.

There was a service error.

400

Domain or Android intent {URI or intent} provided at runtime was not declared in skill manifest.

The deep-link URI or intent provided at runtime was not declared in the skill manifest.

400

Fallback URI type is not supported.

Invalid fallback type specified. Fallback deep links, if provided, can only be websites or universal links. For app deep links, the default fallback is the Apple App Store or Google Play Store entry.

400

Request version does not match skill manifest.

The interface version for AppLinks in the skill manifest doesn't match the requested runtime version.

400

Required field {fieldName} cannot be null.

The skill sent an Alexa for Apps payload that's missing a required field.

400

Customer-facing content does not comply with Alexa skill policy.

There was an issue with user-facing content in the skill's call to the Alexa for Apps API.

400

Adding URI in notification title content is not supported.

The notification title can't contain a link.

400

{dataPath} cannot contain {dataValue}.

One of the custom schemes specified isn't supported.

204

User canceled to use the connection.

Alexa for Apps failed to send any notification because the user canceled during interaction.

Was this page helpful?

Last updated: May 03, 2024