AlexaPy

1.29.20 · active · verified Mon Apr 13

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.

Warnings

breaking 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.
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.
breaking 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+).
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.
gotcha 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.
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`.
gotcha 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.
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.
gotcha 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.
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.

Install

pip install alexapy Install latest version

Imports

AlexaLogin
```
from alexapy import AlexaLogin
```
Main class for managing Alexa account login and sessions.
AlexaAPI
```
from alexapy import AlexaAPI
```
Class for interacting with Alexa devices via the API after successful login.
WebsocketEchoClient
```
from alexapy import WebsocketEchoClient
```
Class for WebSocket communication with Echo devices.
AlexapyConnectionError
```
from alexapy.errors import AlexapyConnectionError
```
Exception raised for connection-related issues.

Quickstart

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.

import asyncio
import os
from alexapy import AlexaLogin, AlexaAPI

async def main():
    email = os.environ.get('ALEXAPY_EMAIL', 'your_email@example.com')
    password = os.environ.get('ALEXAPY_PASSWORD', 'your_password')
    url = 'https://alexa.amazon.com'

    # Initialize AlexaLogin
    login = AlexaLogin(email=email, password=password, url=url)

    # Attempt login
    await login.login()

    if await login.test_connection():
        print(f"Successfully logged in to Alexa account: {email}")

        # Initialize AlexaAPI with the logged-in session
        alexa_api = AlexaAPI(login=login, email=email)
        await alexa_api.get_devices()

        if alexa_api.devices:
            print("Found Alexa devices:")
            for device in alexa_api.devices.values():
                print(f"  - {device['accountName']} (Type: {device['deviceType']})")
            
            # Example: Send a TTS message to the first found device
            first_device_id = list(alexa_api.devices.keys())[0]
            await alexa_api.send_tts(first_device_id, "Hello from AlexaPy!")
            print(f"Sent TTS to {alexa_api.devices[first_device_id]['accountName']}")

        else:
            print("No Alexa devices found.")
    else:
        print("Failed to log in to Alexa. Check credentials or 2FA.")

    # Logout
    await login.logout()
    print("Logged out.")

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →