AMA Kit Setup Flow


This page describes a sample setup flow for a third party accessory device that implements the AMA Kit.

This page will help you implement the setup flow for your accessory and to understand the setup process that your device users will go through as they pair their AMA-enabled accessory with the Alexa app:

  • Instructions for implementing the settings required to initiate the AMA Kit setup flow
  • Description of the responsibilities of the OEM companion app
  • Overview of the process for setting up an AMA-enabled accessory
  • Walkthrough of a sample setup flow that a user goes through when connecting a new AMA-enabled accessory to Alexa, including callouts for the few things that need to be implemented by the device manufacturer.

Initiate the AMA Kit setup flow

To initiate the AMA Kit setup flow, set needs_setup=true for the accessory. Although the Alexa app stores device information to indicate whether to start the setup flow during the next connection, the accessory itself should store the needs_setup=true value. Storing this value with the accessory allows the accessory itself to specify whether it needs any portion of the setup flow executed, instead of relying on the Alexa app, which might not have the most current information. The accessory only returns needs_setup=true if the accessory has never been set up before and thereafter returns needs_setup=false. In this instance, the app on the phone determines if the accessory needs setup by checking the value of the needs_setup parameter in deviceInformation.

To start a setup flow, the Alexa app should send a message to the accessory to indicate that the app has started setup. The accessory should then respond with a success message. These messages are customizable for your accessory and should be flexible for your implementation. The default behavior is for the app to send a start_setup message immediately followed by a complete_setup message.

Responsibilities of the OEM Companion app

As an OEM device manufacturer, you only need to provide a few deep links through your app to help your users set up their AMA-enabled devices:

  • Alexa app installation deep link: A deep link launched within your app's setup flow to prompt first-time Alexa users to download and install the Amazon Alexa app from the appropriate app store, if they have not already done so.
  • Alexa Devices deep link: A deep link to the Alexa Devices screen, which will help users add the new AMA-enabled device to their list of recognized Alexa devices in the Alexa app. Use the following formats to configure your deep links:

    • iOS: alexa://?fragment=v2/accessory-settings/gateway
    • Android:

Overview of the AMA Kit setup flow.

The AMA Kit requires a third party device to execute a setup flow when a user is setting up a new device for the first time. The setup flow includes the following high-level tasks:

  1. Download and install the Alexa app (if the user has not already installed it).
  2. The Alexa app discovers and pairs with the AMA Bluetooth device.
  3. Complete the Alexa setup.

Step 1: Download and install the Alexa app (if needed)

This process walks through a representative sample set of steps for first-time users of the Alexa app who are setting up their new AMA devices. For this scenario, the user is prompted to download and install the Amazon Alexa app from a deep link within the OEM companion app.

Note that before the Alexa setup process starts, the OEM companion app should complete the following tasks:

  • Use Bluetooth to pair the OEM companion app with the AMA device.
  • Perform any firmware updates to the AMA device.

Use the following flow to have the OEM companion app prompt the user to download and install the Alexa app:

  1. On their phone, the user opens the companion app provided by the OEM.

    The OEM companion app searches for the Alexa app, which for this use case, would not be installed on the user's phone.

  2. The OEM companion app uses a deep link to prompt the user to install the Alexa app from the appropriate app store.

    AMA setup sequence
  3. The user installs the Alexa app. When the user opens the Alexa app for the first time, they will be prompted to sign into their Amazon account.

  4. In the OEM companion app, prompt the user to configure the Action button for the AMA-enabled device so that Alexa is set as the voice assistant for that device.

  5. Once the voice assistant is set to Alexa, within the OEM companion app, provide a deep link to the Alexa app Devices screen, as described in Responsibilities of the OEM Companion app

  6. Prompt the user to click the link to the Alexa Devices page to set up the device in the Alexa app.

    Alexa app Settings

Step 2: The Alexa app discovers and pairs with the AMA Bluetooth device.

With the Alexa app installed and opened to the Devices page, the user selects a device to set up, and the Alexa app "discovers" the AMA-enabled device.

The device discovery process has the following steps:

  1. The user taps the + sign in the upper-right corner to add a new device:

    Alexa app Settings

    The Alexa app displays the Add … menu:

    AMA setup sequence
  2. The user chooses Add Device.

    The Alexa app displays a list of device types:

    AMA setup sequence
  3. From the menu of available device types, the user chooses the device type, such as Headphones.

    The Alexa App displays a list detected devices:

    AMA setup sequence
  4. The user taps the device that they want to set up.

    The Alexa app prompts the user to begin setup on their device:

    AMA setup sequence
  5. If necessary, the Alexa app prompts the user to grant the app Permissions for Location and/or Microphone.

    Things to Try

Step 3: Complete Alexa Setup

This use case describes the process flow for a user who has downloaded the Alexa app and successfully paired their AMA device with the Alexa app.

  1. If the user is new to the Alexa app, the app prompts the user for a few pieces of personal information to complete the configuration.

  2. The Alexa app notifies the user that setup is complete. The user can now start using Alexa with their AMA device.

    Things to Try