• Installation and Configuration
  • Enable Two-Step (2SV) Verification for your Amazon account
    • 2SV Authenticator App Key
  • Update HA Core
  • Get the files
    • Easy Mode
    • Manual Mode
  • Configure HA
    • Integrations Page
    • Cookie import (deprecated)
    • CAPTCHA challenge (issue)
    • Configuration.yaml (deprecated)
  • alexapy Dependency
  • Advanced Configuration
    • Configuring Inclusions OR Exclusions (versions >= 0.9.6)
      • Finding names
        • Media players
        • Other devices
      • Integration Page
        • Include Devices
        • Exclude Devices
  • Scan interval (versions >= 1.0.0)
  • Queue Delay (versions >= 2.6.0)
• Uninstalling Integration

Table of contents generated with markdown-toc

Your preferred method needs to be via Authenticator App. No help will be provided for any authentication issues if configured otherwise.

Follow Amazon's instructions You must use an authenticator app to generate your own OTP codes without relying on Amazon sending them to you.

Requires >= 3.3.0

NOTICE: By using this, your configuration files in Home Assistant will have all information to log into your Amazon account since it will have your password and the key to generate 2FA codes. Anyone who gets a copy of your core.config_entries file will be able to log in as you.

Register a 2SV app with Alexa Media Player. ** In case you haven’t enabled 2SV yet, follow Amazon's instructions**

1. Go to your Amazon's Two-Step Verification (2SV) page for your domain

• https://www.<your_amazon_domain>/a/settings/approval
• Add a new app
• Save the key so you can reuse it if you reinstall!

Alternatively, you can re-use an already registered app if you have the key for it.

2. Instead of scanning the QR code, select Can't scan the barcode.
3. Select the bolded value under Enter your Key (e.g., 35T5 LQSY I5IO 3EFQ LGAJ I6YB JWBY JJPR PYT7 XPPW IDAK SQBJ CVXA)
4. Enter the value from Step 3 in the Amazon 2SV Authenticator App Key when adding the integration and an OTP will be automatically generated from now on.

Use your local URL (e.g. "http://192.168.0.123:8123/") for initial proxy callback authentication.

It's highly recommended to always run the latest version of AMP on the latest version of HA Core. At the time of writing, this is AMP 5.0.1 and Core 2024.12.0. AMP 5.0.1 will work on Core 2024.11.x but will force that Core version to use aiofiles 24.1.0 and compatibility issues could exist. Anything older is strongly not advised and no support will be given!

Use HACS. This will also inform you when there are new releases and you can update easily. If installed this way, you can proceed to configuration either using the Integrations Page or Configuration.yaml (legacy).

Copy the custom_components/alexa_media directory from the latest release to your custom_components directory.

Alternatively, you can reproduce the directory structure of the master branch in your config/custom_components directory to create the folder alexa_media. Please ensure you are using raw mode from GitHub if you are saving files from the webpage. Please also ensure the translations directories are copied and you hard refresh your browser to avoid blanks on the form.

After copying all files from the alexa_media directory, your configuration should look like:

config
  custom_components
    alexa_media
      .translations
        *.json
      translations
        *.json
      __init__.py
      alarm_control_panel.py
      manifest.json
      const.py
      helpers.py
      media_player.py
      notify.py
      sensor.py
      services.yaml

Once the files are installed, you’ll need to configure the component.

This is now the only method as YAML configuration has been deprecated.

As of AMP 2.2.0, the component can be configured via the Integrations page in HA.

1. Goto the Settings -> Devices and Services. It should default to the Integrations tab. Alternately, navigate to config/integrations/dashboard
2. On the bottom right of the page, click on the Blue + ADD INTEGRATION button to add an integration.
3. Search for Alexa Media Player. (If you don't see it, try refreshing your browser page to reload the cache.)
4. Enter the required information. (Account/Password/2SV Key)
   1. As of 3.5.0, the login mode is by using the login proxy method which will initiates login through Amazon's UI to verify credentials.
5. No reboot is required. If you need to change the initial login credentials (email/password/2SV key), you can safely delete the integration and re-install it without impacting any automations or scripts. Other settings can be changed for an existing config entry via CONFIGURE in the Integration menu: "Public URL:, "Included/Excluded devices", "Polling Interval", "Multiple Command Queue Delay", "Include entities connected via Echo devices" and "Advanced debugging". "Enable newly added devices" and "Enable polling for updates" can be accessed via the overflow menu (three dots) > System options.

NOTE: If you receive an invalid credentials error and you have confirmed your credentials, check to confirm amazon didn't email you a temporary password.

NOTE: Amazon made some changes to their login process, which results in slight differences of the shown login UI. As just explained above, AMP is using the the login proxy method via Amazon's UI. AMP expects the first Amazon window to be email+password and an optional second window to enter the OTP code. If unsuccessful, it opens the 2nd window as instructed by Amazon which should be the entry of the OTP code. If the login is successful upon returning to AMP, AMP processes the cookie and continues. If however after the second window AMP has not seen a "successful login", it returns to the beginning of the sequence to start over, basically meaning an endless login loop. For example one kind of how the UI is getting displayed is to show 3 pages. The first one for entering the username, the second one to enter the password and the third one would need the OTP password. But the login proxy will reset the login process after the 2nd page and return to the first login page. But the login process can be tricked by selecting something like "create a new account" with your persistent username and password. The UI will complain about a an already persistent account and now the "sign in" can be selected which then shows a page where both, username and password, can be entered.

** No longer supported**

** Deprecated **

This seems to currently be an issue and is likely one of the causes for "Error 500" when setting up

Once you restart HA you may need to complete a CAPTCHA challenge to log in. If so, you will be prompted with a notification alert on your dashboard (on the left side). Complete the CAPTCHA (which may require multiple pop-ups, checking email or your phone for 2FA) and restart again. If the CAPTCHA does not appear, enter anything (e.g. 123456) in the CAPTCHA field and submit. That should cause the CAPTCHA to appear. Then, you may need to enter the password, CAPTCHA, and 2FA and click submit multiple times before it is accepted. Once this is complete you should now see the notify.alexa_media service and media_players.

After downloading the integration in HACS, restart twice. The first restart just installs the alexapy dependency files in the Python libraries. The second restart is required to actually restart and run Python with the loaded dependency and is when 'alexapy' actually becomes part of Python and the component is then live and useable.

Requires >= 0.9.6 HA now has the ability to use the Entity Registry to disable items. That may be the preferred mechanism and we may deprecate this at any time.

Starting with version 0.9.6 you have the ability to only include or only exclude devices (e.g., media_player, switch, alarm_control_panel) that will be added in Home Assistant. **NOTE: These two filters are mutually exclusive so do not attempt to use both! The include filter will ONLY include the devices you specify if they exist and nothing else!

The filters require a case-sensitive name. You can discover the name by looking at the developer-tools/state in Home Assistant and reviewing the friendly_name attribute. If you ever want to determine if a device is being filtered (e.g., you use include_devices and don't see a new entity), you can discover what is being excluded by enabling debug logging on alexa_media.helpers and searching for the Excluding device: line.

2019-09-04 02:08:11 DEBUG (MainThread) [custom_components.alexa_media.helpers] a******e@g*******m: Excluding device: <Entity Guest Room shuffle switch: off>

The entity being excluded is "Guest Room shuffle switch".

The configuration file needs the Amazon name and not the homeassistant entity_id. To find the Amazon name, check the Alexa app or get it from the raw json from here (update to your region url. Specifically, look for the “accountName” attribute in the json response.

{"devices":[{"accountName":"Kitchen"},  {"accountName":"Stairs"}]}

The configuration file needs the HA friendly name. Alexa Guard includes the last 5 digits of the serial number and is admittedly difficult to find without using debug logs. The other switches should follow a standard naming convention, e.g. “Echo Bedroom do not disturb switch”, “Echo Bedroom repeat switch”, “Echo Bedroom shuffle switch”.

Enter your devices during setup without spaces, comma-separated, and case-sensitive. Quotations are not needed.

This Device,Alan's Alexa Apps,Stairs,Garage,Master Bedroom repeat switch

Devices specified here will be the only ones which the integration will include and add to HA (if they exist). Use a comma separated list for multiple devices. Please note it is case sensitive. This entry takes precedence over exclude_devices so you cannot use both!

Devices specified here will be excluded from the available devices discovered and will not be added to HA. Use a comma separated list for multiple devices. Please note it is case sensitive. This entry only works if include_devices is not used

Requires >= 1.0.0 The default scan_interval has been increased from 30 seconds to 60 seconds and is now configurable. There is still a non-user configurable hard limiter at 15 seconds.

Please be careful as each additional Alexa device on your network will contact Amazon and excessive flooding may result in Amazon throttling your account. As of 1.0.0, we have implemented countermeasures so media players will stop polling when idle. Polling will resume automatically if controlled via voice or through HA.

Requires >= 2.6.0

Queue delay controls how long each command will wait to queue up other commands. This will help reduce too many requests errors but will delay running the command. The default is 1.5 seconds. 0 seconds will result in no queuing behavior.

If you wish to uninstall this integration, you can click Uninstall on the component in HACS. First: Remove the integration from your Integrations page, under Configuration > Integrations to avoid an error condition: 'error setting up alexa_media' when you restart HA after you've uninstalled via HACS.