{"id":5107,"library":"alexapy","title":"AlexaPy","description":"AlexaPy is a Python library designed to programmatically control Amazon Echo devices. It acts as an unofficial API, primarily developed for the alexa_media_player custom component for Home Assistant. As of version 1.29.20, it provides functionalities for device interaction, login management, and sending commands to Alexa. Due to its reliance on an unofficial API, the library's functionality may change or cease without warning. The project maintains an active development status, with updates released as needed to adapt to changes in Amazon's unofficial Alexa interface.","status":"active","version":"1.29.20","language":"en","source_language":"en","source_url":"https://github.com/bogusfocused/alexapy","tags":["alexa","amazon echo","home automation","unofficial api","smart home","voice control"],"install":[{"cmd":"pip install alexapy","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Asynchronous HTTP client/server framework.","package":"aiohttp"},{"reason":"Asynchronous file operations; specific version ranges can cause conflicts (see warnings).","package":"aiofiles"},{"reason":"For Two-Factor Authentication (2FA) support.","package":"pyotp"},{"reason":"A next generation HTTP client for Python, often used for async operations.","package":"httpx"}],"imports":[{"note":"Main class for managing Alexa account login and sessions.","symbol":"AlexaLogin","correct":"from alexapy import AlexaLogin"},{"note":"Class for interacting with Alexa devices via the API after successful login.","symbol":"AlexaAPI","correct":"from alexapy import AlexaAPI"},{"note":"Class for WebSocket communication with Echo devices.","symbol":"WebsocketEchoClient","correct":"from alexapy import WebsocketEchoClient"},{"note":"Exception raised for connection-related issues.","symbol":"AlexapyConnectionError","correct":"from alexapy.errors import AlexapyConnectionError"}],"quickstart":{"code":"import asyncio\nimport os\nfrom alexapy import AlexaLogin, AlexaAPI\n\nasync def main():\n    email = os.environ.get('ALEXAPY_EMAIL', 'your_email@example.com')\n    password = os.environ.get('ALEXAPY_PASSWORD', 'your_password')\n    url = 'https://alexa.amazon.com'\n\n    # Initialize AlexaLogin\n    login = AlexaLogin(email=email, password=password, url=url)\n\n    # Attempt login\n    await login.login()\n\n    if await login.test_connection():\n        print(f\"Successfully logged in to Alexa account: {email}\")\n\n        # Initialize AlexaAPI with the logged-in session\n        alexa_api = AlexaAPI(login=login, email=email)\n        await alexa_api.get_devices()\n\n        if alexa_api.devices:\n            print(\"Found Alexa devices:\")\n            for device in alexa_api.devices.values():\n                print(f\"  - {device['accountName']} (Type: {device['deviceType']})\")\n            \n            # Example: Send a TTS message to the first found device\n            first_device_id = list(alexa_api.devices.keys())[0]\n            await alexa_api.send_tts(first_device_id, \"Hello from AlexaPy!\")\n            print(f\"Sent TTS to {alexa_api.devices[first_device_id]['accountName']}\")\n\n        else:\n            print(\"No Alexa devices found.\")\n    else:\n        print(\"Failed to log in to Alexa. Check credentials or 2FA.\")\n\n    # Logout\n    await login.logout()\n    print(\"Logged out.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to log in to an Alexa account, retrieve a list of associated devices, and send a Text-to-Speech (TTS) command to the first detected device. It uses environment variables for sensitive credentials. Replace 'your_email@example.com' and 'your_password' with actual values or set the `ALEXAPY_EMAIL` and `ALEXAPY_PASSWORD` environment variables."},"warnings":[{"fix":"There is no direct fix; users must await updates to AlexaPy to adapt to Amazon's changes, or Amazon may introduce an official API.","message":"AlexaPy relies on an unofficial Amazon Alexa API. Amazon provides no guarantees for this API's stability, and it may change or cease functioning at any time without prior notice, potentially breaking AlexaPy functionality.","severity":"breaking","affected_versions":"All versions"},{"fix":"Monitor `alexapy` releases for updated dependency requirements. If conflicts arise, consider using a isolated Python environment or waiting for `alexapy` to update its `aiofiles` dependency. For Home Assistant users, ensure your `alexa_media_player` integration is compatible with your Home Assistant Core and `alexapy` versions.","message":"Dependency conflicts, particularly with `aiofiles`, can prevent `alexapy` installation or cause runtime errors. For instance, `alexapy` has historically pinned `aiofiles` to a version range (e.g., `aiofiles>=23.1.0,<24.0.0`), which can conflict with other libraries requiring `aiofiles>=24.1.0` (e.g., Home Assistant Core 2024.12.0+).","severity":"breaking","affected_versions":"1.29.4 and later (depending on downstream requirements)"},{"fix":"Reduce the frequency of voice history requests. If possible, await an `alexapy` update that integrates the newer `/customer-history-records-v2` API, which might mitigate rate limit issues, though its implementation may require significant changes in `alexapy`.","message":"Repeated requests for voice history records using older API paths (`/alexa-privacy/apd/rvh/customer-history-records`) can lead to 'Too Many Requests' errors due to rate limiting. Amazon has a newer API path (`/alexa-privacy/apd/rvh/customer-history-records-v2`) which might offer better handling, but integration with `alexapy` requires updates.","severity":"gotcha","affected_versions":"All versions currently using the old API path for voice history."},{"fix":"Try uninstalling and reinstalling the `alexa_media_player` integration in Home Assistant. Ensure correct configuration of `hass_url` if applicable. Clear stored session data (cookies, tokens) and reauthenticate. Verify that 2FA is correctly handled, if enabled.","message":"Authentication issues, including 'NameError: name 'hass_url' is not defined' or persistent reauthentication requests, are common, especially when `alexapy` is used within the `alexa_media_player` Home Assistant integration. This can be due to Amazon's evolving login flow or issues with session persistence.","severity":"gotcha","affected_versions":"All versions, particularly when integrated with Home Assistant."},{"fix":"Ensure the user running `pip install` has appropriate write permissions to the installation directory. In Docker, consider using `docker exec -u <user> -it <container_name> pip install --force-reinstall alexapy` to resolve persistent installation issues or explicitly manage package directories.","message":"Installation issues such as 'Permission denied' errors, especially in containerized environments (e.g., Docker for Home Assistant), can occur when `pip` attempts to install `alexapy` into restricted directories. Missing `alexapy` directories after installation can also lead to 'module not found' errors.","severity":"gotcha","affected_versions":"All versions in restrictive or containerized environments."}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}