Alexa for Apps Skill Connection Request Reference

Note: Watch the replay of Alexa Live ‘22 on demand. Catch the latest on ambient intelligence, smart home, and AI.

Note: Alexa for Apps is a developer preview and might change as Amazon receives feedback and iterates on the feature. To use this feature, you must register for the preview. If you have questions or feedback about Alexa for Apps, please email alexaforapps-help@amazon.com.

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.

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

links object in the input payload

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

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

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

Deep link reference

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.